Principles of Software Documentation


Some months ago I've given an internal presentation about principles that should guide writing software documentation. Since I think these principles are not Zemanta specific I'm sharing them with you.

  1. Source code and running services are the ultimate documentation!
  2. No documentation is much much better than misleading/outdated documentation!
  3. Out of sight, out of mind! Documentation should be close to the source code and the running services!
  4. Document only what's absolutely necessary (data structures, development environment setup, release and deployment procedures)
  5. Documentation should be part of company culture and engineering pride!

From my experience forcing documentation comes in waves of total enthusiasm and total negligence with both of these phases producing inadequate documentation. If you really want to improve your documentation practices I'd recommend doing the following things: (a) make documentation part of your company's culture, (b) do code reviews and (c) do more frequent module change-hands.

For the most succinct description of how most software documentation looks like check this Geek and Poke comic.