Who Should Write the Docs?

User Documentation: It's tempting to hire an unemployed English major so that the writing is good. But the point of documentation is not good writing, it's useful writing. So skip on the writing expert and pick a system user. Someone who actually knows the pitfalls of the software in a real work environment will create a much more interesting and useful product. (Maybe hire the English major as an editor)

In Line Code Comments: I'm amazed at how many developers don't comment their code. I'm not talking about /* Start of loop */ -- oh duh. I could see that in the code. That kind of comment is stupid. What I am talking about is /* this logic is more complex, but it handles leap year where other alternatives don't */. In 5 years what would I need to know about this code? Document that. We need to demand of ourselves and our peers that undocumented code is unfinished code.

Compilation/Configuration Comments: For small shops with limited resources this is critical. Either the developer or whoever is in charge of deployment has to document this stuff. It's not fun. It simply must be a discipline.

Design Documents and Other Construction Artifacts: Nobody. No, I don't really mean that. But, as a general rule it seems that too high of a percentage of documentation time is spent generating documents that are useful for only a brief period during the early construction phases. These "big picture" documents are important. But there also needs to be detailed technical documentation describing the finished system. That step is so often left out.

Wiki, wiki, wiki: A document is never finished. Make it easy to update.

Why Don't We Document Our Software? Part 1: False Excuses

Quick what's the right answer:

a) We're bad writers

b) We don't like to write

c) We are too busy

d) All o the above

OK, trick question. The answer is: e) none of the above. Here is why:

a) Most software developers have at least a bachelor's degree from a liberal arts school. As a general rule we have at least as much training as the biology major writing the user documentation. Often we have more. Software developers write blizzards of email and fill up message boards with numerous comments. We can write.

b) If this were true why are so many open source projects some of the best documented systems out there? When programmers develop "for fun" we write documentation.

c) There is a kernel of truth in this. Everyone is busy. But the truth is we find time to do what's important to us (and our managers). Documentation just isn't.

In my next post I'll examine the real reasons we don't document our software systems.