The Value of Documentation
Devs often talk about the importance of documentation. More specifically, they usually complain about systems which have none (“How are we supposed to know what’s going on here?!“), some (“Well, I guess something is better than nothing, but come on!“), or lots (“Are you really expecting me to read all this?!“).
I was once in an agile training class when the issue of documentation came up. The instructor asked whether we thought documentation was important. The responses were a mix, but one guy in particular was adamant that documentation isn’t necessary at all. When asked why he simply said: “Well, I’m a developer and I never read it“.
Interestingly, even though devs generally dislike reading documentation, they often ask for it. That’s because when devs ask for documentation, what they’re really asking for is an answer to two questions:
- I want to know what the system is supposed to do
- I want to understand why the system was implemented in this way
What is this thing supposed to do?
Ideally, a system would have a requirements document describing behaviors implemented within it. To be especially useful, this document would be specific enough to address implementation details. And of course, it would be up to date.
Bad news is that creating this document as a document is next to pointless because the effort required to maintain it is prohibitively high for most systems. Good news is that a well-written set of functional tests can probably serve a similar purpose and be automatically up-to-date at the same time.
Why does it work like this?
This one is trickier. Again, ideally there would be some living “decisions” document describing the thought process behind major architectural decisions, algorithms, etc. And again, the cost of maintaining such a document would probably make it not viable. There are a few things that could help:
- Self documenting code, especially in describing algorithms
- Naming conventions reflecting participants in known design patterns (ex: Strategy class)
- Timely (but very limited) comments describing the thoughts behind an implementation
- Maybe code contracts
Final Thought
I don’t mean to imply that written documentation is entirely useless. As long as you can address the issue of staleness, written documentation could actually be helpful. There are teams, for example, that are using wikis to share knowledge with pretty good success.