Project Documentation

• By Mashooq Badar
• Posted 07 Feb 2013
• team

Our 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 ...