I have a generally dim view of documentation. It’s expensive, difficult to do correctly, rarely updated, and even more rarely used. That said, however, I still think some of it is necessary. Those who say “it’s all in the code, just read it” are completely missing the point about what documentation is for.
To help myself make sure any document I write will be useful and kept up to date, I like to think of (useful) documentation serving one of several purposes. Any single document should not attempt to serve two of these purposes at the same time:
- Give Me Context:
- Keep a Reference:
- Tell Me How To Do Something:
- Dictate the Law:
- Define the API:
Most team leads and architects create this kind of documentation on whiteboards several times a day, but for some reason never commit it to a document. This kind of information rarely changes once it’s decided and will be viewed by many different kinds of people of varying technical aptitude, so it’s worth spending the extra time to connect all the dots, draw pretty diagrams and bring out your best prose. An example of this kind of document is a high-level architecture diagram.
This should be all, and only, the information I have been told a hundred times but keep forgetting anyway. Assume the reader already has the context or knows where to find it and is here to get information quickly and get out. Should be very “fact-heavy” and structured in a way that’s easy to maintain because it changes often. Wiki pages are a fantastic medium for these. An example of this kind of document is a table of server machine names and the JMX ports their production processes listen on.
The person reading this kind of document has a very specific task to achieve and may or may not care about the context. Keep focused on the task and give every last detail, down to the button clicks, urls to type, etc. Assume your reader is a monkey who knows nothing. Litter the document liberally with links to context diagrams and reference pages–that way you can keep the flow clean and the reader moving from one step to the next without getting lost. Wiki pages are also a great medium for this kind of document. A great example of this kind of document is a set of instructions for a new developer on your team to set up his development environment.
These are the kind of document none of us likes creating and even fewer of us like reading. But unfortunately sometimes you just have to lay down the law about things like coding standards, developer access to production environments, etc. Think of these like a legal document and try to be as absolutely clear and succinct as you can. Also, try to give some background on the reasons for each rule to give users some context for interpreting the spirt of the rule when they encounter an ambiguous situation.
I almost left this category out, but then decided that API documentation is indeed a unique beast. API documentation should define only public apis that you actually intend people to use and should be generated by something like JavaDoc, with one or two summary pages to point people to the right places to start for different kinds of tasks. Make sure that you spell out the contract you expect people to follow when calling your API.
There are some documents you might notice I’ve left out. For example, I’m not a big beliver in things like comprehensive class diagrams, data dictionaries, and down-to-the-letter technical specs. If you can generate those kinds of artifacts directly from your build, then great, please do it. Otherwise I tend to agree with the “read the code” purists and don’t think their use outweighs their expense. Likewise, I don’t really believe in support “run books” and knowledge bases because every support issue is different. If you know the context then you’ve got 90% of what you need and a searchable ticketing system will take care of the rest.