Chapter 11. Document Just Enough
Je n’ai fait celle-ci plus longue que parce que je n’ai pas eu le loisir de la faire plus courte. (The only reason why I have written this long is because I did not have the time to shorten it.)
Document just enough for the development team to have a common understanding of design decisions and nonfunctional requirements.
Keep documentation current, concise, and accessible.
This improves the development process because documentation retains knowledge and helps to avoid discussion.
Some of the previous chapters have already dealt with documenting in some way, such as the Definition of Done, coding style standards, and third-party code policies. Because documentation is a form of knowledge transfer, consider that for all developers the following should also be clear:
- Design decisions
By this we mean the fundamental choices that are made about the subdivision of the system into components, but also how the system is implemented, how input is handled, and how data is processed. In this sense, design decisions cover high-level architectural choices as well as low-level design patterns. They are based on assumptions about the circumstances in which the system will run (for instance, requirements and criteria).
- Requirements and criteria
Functional requirements and nonfunctional criteria describe what the system should deliver when, and how.
- Testing approach
Decisions about what, when, and how to test.
- Code ...