Tuesday, May 20, 2008

Making Documents Lean

I was going to write a whole post about lean documents, but while doing my research, I quickly came across this article by Scott Ambler over at AgileModeling.com. It's a long read, so if you're short on time, read the Critical Points and Why Do People Document? sections. The former makes a great print-out list for your cubicle wall. The latter is more politically sensitive, so I wouldn't post it in public (since it's probably only relevant if you have a traditional, political workplace), but it is a great resource if you're interested in trying to introduce agile ideas and want to avoid resistance and backlash.

If you're really short on time, here are some highlights:
  • The fundamental issue is communication, not documentation.
  • Agilists write documentation if that's the best way to achieve the relevant goals, but there often proves to be better ways to achieve those goals than writing static documentation.
  • Document stable things, not speculative things.
  • Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
  • Prefer executable work products such as customer tests and developer tests over static work products such as plain old documentation (POD).
  • You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose to make that investment.
  • Well-written documentation supports organizational memory effectively, but is a poor way to communicate during a project.
  • Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
  • With high quality source code and a test suite to back it up you need a lot less system documentation.
  • The benefit of having documentation must be greater than the cost of creating and maintaining it.
  • Ask whether you NEED the documentation, not whether you want it.
  • The investment in system documentation is a business decision, not a technical one.