Decide How Much Documentation Is Needed
One of our Agile 2 Foundations students works at a machinery manufacturer, and related the story that circa 2014 his company brought in Agile consultants who told the teams that documentation was “not Agile”. The result was that for a period of three years they created little documentation, with the outcome that communication between teams suffered greatly.
Documentation is essential; but too much documentation can be as bad as no documentation: it needs to be the right amount for the situation.
There are two general purposes of documentation:
Learning
Reference
These are very different. Documentation intended for learning should generally start with the simplest case, and progressively cover other cases. Also, documentation intended for learning is rarely complete, but instead only covers the range of concepts.
In contrast, documentation intended for reference needs to be extremely complete, detailed, and precise.
A lot of the documentation that we see today for home-grown single-maintainer software products tends to combine these two purposes, with the result that the documentation is poor. Single-maintainer tools often provide some examples of the common case, but do not provide reference documentation. However, if one looks at the most successful software tools and ecosystems, such as Amazon Web Services and the Java APIs, they are expertly documented, with both learning documentation (usually expressed as “quick-start”) and reference documentation.
Ideally, all documentation should,
Have minimal boilerplate.
Be dynamic, easy to locate, and easy to change.
Anyone can update it or add pages, so that no one has to wait for someone else to make a change.
Have change history built-in, so that incorrect changes can be reversed.
Allow people to subscribe to pages so that they are notified when something changes. This enables someone to check that changes that have been made are correct, and possibly reach out to the person who made the change to discuss it.
Product development teams maintain documentation about the evolving technical design of the product. This internal documentation should,
Describe each design decision.
The assumptions or vocabulary (e.g., component model) used by the design decisions.
The reason for each design decision.
Number 1 is often expressed in diagram form. For example, a diagram of a software system’s deployment expresses the networks and interconnection routes between components. In that case, number 2 might define the symbols in the diagram. For example,, certain symbols might represent certain kinds of deployed components, such as microservices, software-defined networks, firewalls, and other kinds of components.
Documenting the reason for each design decision is very important. For example, if there are two service clusters instead of one, why are there two? Documenting the reason for each decision enables agility because as things change, people can see why things are the way they are, and be able to make a quicker decision about whether they can change things to meet a new need.
Documentation can be burdensome because it has to be kept up to date. It is essential that updating documentation be part of the “definition of done” for any change to a system. Keeping the documentation lightweight and free of unnecessary boilerplate lightens the burden.