Documentation

alpha pre-release v.0.2:

alpha pre-release v.0.1:

Official Release v.1.0.1. Production-Ready. A.G. (c) 2017. All Rights Reserved.

Official Release v.2.0.1. Production-Ready. A.G. (c) 2023. All Rights Reserved.

• Tom de Lancey describes an approach on documentation:
• "(…) we do not want to waste time and effort in documenting something that we have not yet discovered how to do. We document as we discover. We document only what we actually DID, as opposed to what we thought we were going to do."
• Tom de Lancey, Emergent Documentation: One way that agile is very different from waterfall, 2013

Critical Points:

1. The fundamental issue is communication, not documentation.
2. 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.
3. Document stable things, not speculative things.
4. Take an evolutionary approach to documentation development, seeking and then acting on feedback on a regular basis.
5. Prefer executable work products such as customer tests and developer tests over static work products such as plain old documentation (POD).
6. You should understand the total cost of ownership (TCO) for a document, and someone must explicitly choose to make that investment.
7. Well-written documentation supports organizational memory effectively, but is a poor way to communicate during a project.
8. Documentation should be concise: overviews/roadmaps are generally preferred over detailed documentation.
9. With high quality source code and a test suite to back it up you need a lot less system documentation.
10. Travel as light as you possibly can.
11. Documentation should be just barely good enough.
12. Comprehensive documentation does not ensure project success, in fact, it increases your chance of failure.
13. Models are not necessarily documents, and documents are not necessarily models.
14. Documentation is as much a part of the system as the source code.
15. Your team's primary goal is to develop software, its secondary goal is to enable your next effort.
16. The benefit of having documentation must be greater than the cost of creating and maintaining it.
17. Developers rarely trust the documentation, particularly detailed documentation because it's usually out of sync with the code.
18. Each system has its own unique documentation needs, one size does not fit all.
19. Ask whether you NEED the documentation, not whether you want it.
20. The investment in system documentation is a business decision, not a technical one.
21. Create documentation only when you need it at the appropriate point in the life cycle.
22. Update documentation only when it hurts.

Agile/Lean Documentation: Strategies for Agile Software Development

Best Practices for Increasing the Agility of Documentation

1. Prefer executable specifications over static documents
2. Document stable concepts, not speculative ideas
3. Generate system documentation
4. Keep documentation just simple enough, but not too simple
5. Write the fewest documents with least overlap
6. Put the information in the most appropriate place
7. Display information publicly
8. Document with a purpose
9. Focus on the needs of the actual customers(s) of the document
10. The customer determines sufficiency
11. Iterate, iterate, iterate
12. Find better ways to communicate
13. Start with models you actually keep current
14. Update only when it hurts
15. Treat documentation like a requirement
16. Require people to justify documentation requests
17. Recognize that you need some documentation
18. Get someone with writing experience

Agile/Lean Documentation: Strategies for Agile Software Development

BACK TO INDEX OF REPOSITORIES

A.G. (c) 2017. All Rights Reserved.