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 documentation
-
Code is ideally self-documenting, but for complex pieces of code you can supply reference implementations, and when supplying an API, you can use automatically generated API specifications.
We explain why good documentation is important, and how you can arrive at good documentation.
Motivation
Documentation is important for your development team, in order to have a common understanding of how the system is structured and how it should behave. Technical documentation is also important to retain knowledge of the system, whether it is for new developers or for the external world (in case others are to maintain the system as well). Documentation also helps you to see whether you are reaching your goals.
Documentation Retains Knowledge and Helps to Avoid Discussion
Documentation of your design, assumptions, and requirements is a means of knowledge transfer, in case new developers join the team or when your codebase becomes available to external developers. When introducing new developers, they should be able to get acquainted quickly with the system and its design.
When you have documented why certain design decisions were made, and explain the rationale behind these decisions, this helps avoid discussions later. That way developers can consider, for example, whether assumptions made in the past are still valid. When the code that is written is aimed to be exposed to the outside world with APIs, you require an API specification and greatly help others with a reference implementation.
How to Apply the Best Practice
Good documentation is concise, current, and complete, and these properties should be enforced by quality control.
Keep Documentation Current, Concise, and Accessible
Documentation is only useful if you can depend on a reasonable amount of currency. Therefore, good documentation is concise and is actively kept up-to-date (thus requires maintenance effort during development).
Documentation tends to be complete only up to a certain level of detail and therefore can remain concise. Indeed, it is not necessary to document all implementation details, as source code (structure) and tests should be self-explanatory. High-level design decisions such as technology choices should be documented in order to be reviewable when circumstances change. Such documents should in general not consist of more than 10 pages for any subject. If it does, it usually contains a high level of detail. This can be useful in some cases, but make sure these are documents to refer to from other, shorter documents. The general rule of thumb is that a document that is not a reference manual can be read and understood within an hour.
If documentation is unretrievable or scattered, it cannot be used properly. Therefore it is a prerequisite that documentation is stored and maintained in some central location that allows for access to those who need it (for proper security that should be on a need-to-know basis). This can be part of a central version control system, a wiki (that contains version control management), or similar other repositories.
Important
Do not think of documentation as a “Write Once, Read Never” device. It should be actively maintained simultaneously with the system to be valuable.
Required Elements of System Documentation
All design choices should include basic assumptions underlying those choices. Those assumptions are based on the circumstances in which the system is available. For example, when defining a performance requirement one may assume a certain number of concurrent users and intensity of usage. Once those assumptions are documented, they can be reviewed, challenged, and improved when the circumstances change.
The form that documentation is presented in is up to the team. Typically, tests, use cases, and scripts describe well what the system should do and what it should not do. Consider that there are different things you want to know about a system as a developer if you are building on it. Therefore, in whatever form, system documentation should include the following:
- Goals and functionality
-
The goals of the system in terms of functionality and value for users and the organization as well as what functionality and behavior the system should provide to achieve those goals.
- Internal architecture
-
Division of the system in functional components. A well-designed source code organization should be able to show this division.
- Deployment
-
The way a system behaves can largely be influenced by the environment in which it runs. Therefore its deployment architecture and its assumptions should somehow be documented; e.g., visualized and described.
- Standardization
-
Agreements on decision choices for the technology stack, technology-specific usage, and the internal (code) architecture. For more on standardization, see Chapter 9.
- Owner and process
-
To ensure that the documentation is and stays current, each type of documentation needs an owner and a process understood by the maintenance team that they adjust documentation once assumptions, design choices and /or circumstances change significantly. For code, tests, and scripts, the one that is adjusting it tends to take responsibility naturally to update it (be it a document, comments, test cases, etc.).
Quality control is enforced to keep the nonfunctional requirements in check
After defining nonfunctional requirements, development should be actively controlled for adherence to those requirements. Preferably, this is an automated process (part of the development/test pipeline), but it should at least appear as part of the Definition of Done. In case of an automated process of quality control, the nonfunctional requirements also require a testing strategy. For more on quality control, refer back to Chapter 9.
Managing Your Documentation
Assessing your documentation is a delicate issue. With too much documentation, the maintenance burden becomes high, knowledge is harder to find, and often large documents are neglected. With too little, you are at risk of not knowing enough about the system, which may lead to making wrong decisions and assumptions. However, the code should be clear enough to document itself to a large extent. Perceptions of what is good documentation may also depend on experience. More experienced developers generally need less documentation to understand the technical intricacies of a system.
With the following GQM model we focus on the maintenance burden and the quality of documentation.
-
Goal A: To understand the maintenance burden of documentation.
-
Question 1: How much time is being spent on maintaining documentation?
-
Metric 1: Number of hours spent on documenting. This assumes that developers can and do write hours specific for administration. This should neither be zero, nor a significant investment. Expect documentation investment to be high in beginning stages of system development, reducing to a stable figure. The risk notably is in arriving at “too much documentation to maintain” after which maintenance becomes neglected. What is “high” should therefore be discussed with the team based on this metric.
-
-
-
Goal B: To understand the quality of our documentation (completeness, conciseness, and currency) by taking inventory of developers’ opinions of them (after all, they are the ones using it).
-
Question 2: What do developers think about the documentation’s quality?
-
Metric 2a: Opinion per developer about the quality of documentation overall.
-
Metric 2b: Opinion per developer about the documentation’s completeness for their purpose.
-
Metric 2c: Opinion per developer about the documentation’s conciseness for their purpose.
-
Metric 2d: Opinion per developer about the documentation’s currency for their purpose.
-
-
These opinions can be rated on a scale (e.g., from 1 to 10). The outcome of these measurements should be discussed with the team. Just as with standards, when developers have widely different opinions, this may be caused by difference in experience. When the measurement shows that everyone agrees that the documentation is not of high quality, you know that improvements are necessary. This assessment could be repeated every six months, for example.
There is a clear trade-off between completeness and conciseness. There is also a relationship between the maintenance burden and currency. Finding the right balance is dependent on team preference and development experience.
Common Objections to Documentation
Common objections to documentation are that the team does not get the time to write documentation, that there is disagreement in the team, or that knowledge about the system is too scattered to write documentation.
Objection: No Time to Write Documentation
“We do not get the time to write documentation from the business!”
Consider that maintaining documentation is not a task in itself. It is part of regular development, when software changes thoroughly or when the software design has intricacies that are hard to understand quickly (for new developers). Documentation is not necessary for each modification, but lack of it may especially hurt future maintenance when modification concerns high-level design decisions. Consider also that the requirements or changes as defined by the business may themselves serve as documentation.
Objection: Disagreement in the Team
“My development team does not agree on the internal architecture of the system.”
Documentation is something that the whole team should agree on. When there is friction between team members, you should appoint a quality champion within the team with the task of pulling the rest of the team along. Typically a lead/senior developer with a software architect’s role can make the final decisions on architectural issues, in consultation with the team. If this is still difficult, consider having a workshop to evaluate the possibilities of revising the architecture or to explore the current issues.
Objection: Knowledge about System Is Scattered
“Knowledge about the system is too scattered to achieve consistent documentation.”
Consider that you cannot document all knowledge. Start by documenting what you know now and write down the assumptions that you make under the current circumstances. This does require active maintenance when the situation changes or new knowledge is gained. This maintenance should be part of a standard (e.g., part of the DoD). That way, it becomes a shared responsibility for the team. In practice it works well if one person is assigned an authority responsibility to remind others to retain discipline to maintain documentation.
Metrics Overview
As a recap, Table 11-1 shows an overview of the metrics discussed in this chapter, with their corresponding goals.
| Metric # in text | Metric description | Corresponding goal |
|---|---|---|
DOC 1 |
Number of hours spent on documentation |
Documentation maintenance burden |
DOC 2a |
Developers’ opinions on documentation quality overall |
Documentation quality |
DOC 2b |
Developers’ opinions on documentation completeness |
Documentation quality |
DOC 2c |
Developers’ opinions on documentation conciseness |
Documentation quality |
DOC 2d |
Developers’ opinions on documentation currency |
Documentation quality |
Because documentation should describe common understanding, this chapter is closely related to the topics of standardization (Chapter 9) and the usage of third-party code (Chapter 10).