I was in Brussels last weekend to visit a friend, and had a chance of meeting up with a group of highly skilful and visionary people. We had a very interesting chat, and one point was about documentation came up. Seemed like everybody has the same pain, reading and writing technical documents consume an incredible part of any developer’s day, usually most of the work done is about searching the right needle through a pile of garbage.
It is amazing that over the years that hardware technology is evolved a lot. Not so much as it, software has also progressed and proved some quality.
But one thing couldn’t make the big move: Documentation. No, I know we have better word processors, heck, I am using one for this entry. We have the enough technology to write more old styled documents. We have been reading tons of papers 30 years ago to accomplish a single development task, thanks to the internet, web 2.0 or whatever brought us, we now have wikis, podcasts, screenCasts and blogs which speak to different senses and styles. Of course there still is some technical problems, such as indexability, searchability, and relevancy to the need of these but it is getting better over the time.So what is my problem ?
Ok, I am gonna say it. It is that we DON’T get enough benefit of all these in our daily business environment.How many of you have been left with a legacy code ? Surely most of you. How much are them was documented ? I bet since most aren’t, it is not a few either. And why don’t we get any podcast, or a web cast on, let’s say Provider Infrastructure for Insurance, or Dealing with Leasing Options in Banking where we are more than happily get provided hundreds of pages ?
Now known that while handing over the legacy code, pairing with the person who originally wrote it is one of the best things that you can do, why does this information fly? When that person goes away either you loose all the info, or if you have a documenting process it might be even worse: you’ll face the hungry monster of 200 pages, which hasn’t been maintained like 10 years ago.
My point is, let’s produce those documents keeping in mind that a person will read it - not that because writing a thick book on the subject makes us seem more intelligent and hardworking. I want to see more agile documents. Those include:
- If a document is longer than 20 pages, please consider breaking it down to multiple ones.
- If you can tell more with less words, please do so. Usage of patterns for e.g, applies well here.
- If you can tell more without any word, even more appreciated. Using pictures, diagrams or even comics sometimes, usually reach to the point
- Know your audience, and produce the document for him/her not for comfort of yourself. If I am your audience, know that I am a highly technical guy and not a native English speaker. Don’t assume that I know what you know, such as your sector’s details and don’t think that I am dying to look at your design document to learn what a Memento Pattern is all about.
- If you think that you can express better if you speak, do a podcast and link it from that document. If you want to show a process, let’s say a migration chain, don’t hesitate to record a screen cast. It will take only 2 mins and will stay there forever, so you won’t spend your time going over and over it to the newbies joining the team. You don’t need to be an expert, as these will stay internal.
- Blog about what you found. Put it in the company wiki. Get angry with the people asking you questions before looking at the wiki. Girr !
- Use documents to increase the quality of communication, not the time spent on it. If you need a meeting to talk about a 100 page document, either the document or meeting is not to its full intent.
In business environments, I see an incremental Agile Documenting Fear (term stolen from M.Fowler as in Parser Fear) that leads us to the apocalypse of inconsumable documents. IMHO, that’s something that we should avoid for our own goodness.