Project Documentation

ImageOur project has a number of places where we keep documentation. To name but a few we have a Wiki, Sharepoint Site, Jira etc. When I want to know something that is specific to my project the first place I look is my e-mail archive or shout a question to my team and if it’s a general question about a framework or library then I go for the Google.

We had an issue today with the Oracle Pooled Datasource XML Type handling. Our XML retrieval was coming back with an extra space in the middle of the document. Naturally this was a general question and we hit Google. A few people had some similar issues and had some not so great workarounds mentioned. I then happened to be talking to one of my colleagues and mentioned the problem to him. He told me that they faced this problem a while back and developed a much nicer work around. I would’ve gone with the ugly workaround from the web if I hadn’t spoken to him.

So why the long story; well if the web is the first place we hit for general questions then why don’t we document our general questions on the web so that we may have a better chance of finding it rather than buried deep in someone’s mail trail or an internal wiki or even worse in someone’s head.

The same goes for project specific documentation – often the most useful insights are buried in mail trails – that’s why I search my mail archive before I look anywhere else. It’s not the most effective place to keep some of the most valuable project documentation. The problem is some of these valuable mail trails start with some ad-hoc point-to-point conversation.

I once worked on a project where they had an internal version of Stack Overflow and all discussion, questions, insights, messages were conducted using this application creating a wealth of searchable project documentation. However this does not fit the bill completely because you have to make a conscious decision that the point-to-point conversation you are about to have will end up in a valuable mail trail.

Only if there was a button to “promote” a mail-trail into a searchable forum? Maybe there is – I’m hitting Google …

Advertisements

Speed Reading

It's not often you read a book that changes your perceptions. Speed Reading by Susan Norman/Jan Cisek is one of them. I've always loved reading books but had felt that I read very slow. According to the book reading has many types and you employ a type that suits the purpose for your reading. The problem was not the fact that I read slow but that I only had one style of reading irrespective of what I was reading and why.

The “slow” type where you read every individual word is one where the purpose is “reading for pleasure”. Other styles such as Skimming (looking for key words), Scanning (Looking for very specific information) are more useful for quickly gleaning info from a book.

There are many techniques listed in the book that can make reading a more productive experience. Examples include using your peripheral vision more effectively, preparing your mind before reading, employing your sub conscience mind etc.

Some of the techniques may be quite difficult to master but it will at least change how you view reading. You may even discover that you already use some of these techniques naturally.