Agile documentation should:
- Keep it simple (KIS), keep it lean (KIL).
- Clear and unambiguous.
- Lightweight, dot points, single sentences, to the point.
- Consistent presentation with whitespace.
- Well designed, organized, structured.
- Prefer diagrams over words.
- Easily searched and navigated.
- Easily updateable.
- Just in time (JIT).
- 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.