Documentation

Original posts from January 2015

I like writing documents. Because of the way I was indoctrinated early on in my career, I learnt that documents with fancy names meant that you were more mature in your process. Documents are meant to transfer information around between different people, departments and companies. Its meant to solidify and get agreement on specifications. There's different templates, formats, audiences...the whole deal.

So early on I relished writing documents. I was told that it was important to document the requirements for a system, then document the design of a system after it was built, then document the ...... you get the message.
I then became a consultant, and documents were the measure of progress, and sometimes even the actual thing that we sold. I have worked on projects where for 3 months a team of us created a single power point deck.
In the IT industry, documentation is the lingua franca, the currency of the day. Its what we trade in. "I will send you the Technical Specification once you send me the Business Requirements". So we spend our day writing reams of documents, and project meetings ticking off the documents we have written. But there is one big problem with this whole process:

Nobody reads documents!

There, I said it! Nobody ever reads them, until the person has left the company and the next guy needs to the figure what has been done. This ignores the people who review documents just to nitpick the format, section placement, etc. But nobody reads documents to actually transfer knowledge, and get agreement on a project thats active. Because its just simply a broken way to transfer knowledge - you lose context, the formats and templates force you to write in Enterprise, so you lose the gist of what was intended.

Then there is the technicalities - how do I provide feedback on a document that I actually have read: using comments in Word, separate email referring to section numbers, etc. How do I provide comments/feedback on wiki articles?

C'mon, we need a better way to do this?