Project Documentation

07 Feb 2013

SC London
The place where passionate Software Craftspeople, Community, Experts & Thought Leaders come together
Book your ticket now!

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

Get content like this straight to your inbox!

Codurance Logo

Software is our passion.

We are software craftspeople. We build well-crafted software for our clients, we help developers to get better at their craft through training, coaching and mentoring, and we help companies get better at delivering software.

Latest Blogs




Contact Us

3 Sutton Lane
London EC1M 5PU

Phone: +44 207 4902967

2 Mount Street
Manchester M2 5WQ

Phone: +44 161 302 6795

Carrer de Pallars, 99
08018, Barcelona

Phone: +34 937 82 28 82

Email: hello@codurance.com