Building Software Teams

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.)

Blaise Pascal

Best Practice:

• 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 ...