Ian Berry IT Blog

Agile documentation should:

1. Keep it simple (KIS), keep it lean (KIL).
2. Clear and unambiguous.
3. Lightweight, dot points, single sentences, to the point.
4. Consistent presentation with whitespace.
5. Well designed, organized, structured.
6. Prefer diagrams over words.
7. Easily searched and navigated.
8. Easily updateable.
9. Just in time (JIT).
10. Stable (dont document rapidly changing work).

Ideally documentation should convey information clearly, concisely, reduce information silos (i.e. knowledge only known by an individual/team) and reduce re-learning time across teams & organisations.

Reference Material

Extract from  Agile Modelling:

Agile documentation principles

• 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.
• Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
• Travel as light as you possibly can.
• Documentation should be just barely good enough.
• Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
• Models are not necessarily documents, and documents are not necessarily models.
• Documentation is as much a part of the system as the source code.
• The benefit of having documentation must be greater than the cost of creating and maintaining it.
• Developers rarely trust the documentation, particularly detailed documentation because it’s usually out of sync with the code.
• Ask whether you NEED the documentation, not whether you want it.
• Create documentation only when you need it at the appropriate point in the life cycle.
• Update documentation only when it hurts.

When is a document agile?

• Agile documents maximize stakeholder ROI.  
• Stakeholders know the TCO of the document.  
• Agile documents are “lean and sufficient”.
• Agile documents fulfill a purpose.  
• Agile documents describe “good things to know”.
• Agile documents have a specific customer and facilitate the work efforts of that customer.  
• Agile documents are sufficiently accurate, consistent, and detailed.