Effective Documentation Practices
Incorrect documentation is worse than missing documentation. Follow these principles to evolve a body of content helpful for internal and external members of any team. Give developers systems that allow them to make documentation and code changes. Start documentation before development. Accept repetition in the documentation. Structure content to help readers identify and skip concepts they already know. Add examples in the content. Store sources as close as possible to the code they document. Order content to cover prerequisite concepts first. Ensure that all the publications in the body of documentation can answer all questions the user is likely to have. Have a wiki as your central base. Have a document repository where to put your documents, diagrams, etc.
Amazon Web Services has published a guide for using architecture decision records (ADRs). They recommend a process to adopt and review ADRs in software engineering teams. It includes the decision but also its context and consequences. The result is a collection of approved, rejected, or superseded ADRs in a decision log.
Any team member who identifies a decision like that should create an ADR. Templates can simplify ADR creation and ensure it captures all the relevant information.
The team member creating an ADR is its owner, who handles maintaining and communicating its content. , the ADR owner provides an ADR in the “proposed” state, which means it is ready for review. Then, the owner arranges a team meeting to review and decide if the ADR is accepted, requested for rework, or rejected. If the team finds that the ADR needs improvement, it preserves the “proposed” state, and the owner and other team members work on the refinements. Otherwise, the ADR status changes to “accepted” or “rejected” and becomes immutable. If the team needs to update that decision, the team should propose a new ADR, and when this ADR is accepted, it supersedes the previous. Do not take “architecture” too or interpret it too. Have a quick reference to understand what has been done in the past. Allow us to share our thinking and methods with our stakeholders. Maintain open and transparent communication inside and outside of our teams. Architecture for agile projects has to be described and defined. Not all decisions will be made at once, nor will they be done when the project begins.
Agile methods are not opposed to documentation, only to valueless documentation. Documents that assist the team can have value, but only if they are kept current. Large documents need to be kept up to date. Small, modular papers have at least a chance of being updated. Nobody ever reads large documents, either. Those documents are too large to open, read, or edit. Bite-sized pieces are more straightforward for all stakeholders to consume.
One of the hardest things to track during the life of a project is the motivation behind certain decisions. A new person coming on to a project may be perplexed, baffled, delighted, or infuriated by some past decision. This response may be OK if the decision is still valid. Yet, it may not be good if the context changes and the decision should be revisited. This person needs to understand the rationale or consequences of having two choices. Each ADR describes a set of forces and a single decision responding to those forces.
The decision is central so that specific forces may appear in many ADRs. We will keep ADRs in the project repository under doc/adr/NNN.md. We should use lightweight text formattings language like Markdown or Textile. ADRs will be numbered. Numbers will not be reused. If a decision is reversed, we will keep the old one but mark it as superseded. We will use a format with a few parts so each document is easy to digest.
Title: These documents have names that are short noun phrases. For example, “ADR 1: Web framework decision Ruby on Rails 7” or “ADR 9: Moving architecture to Hexagonal”.
Context: This section describes the forces at play, including technological, political, social, and project local. These forces are in tension and should be called out as such. The language in this section is value-neutral. It describes facts.
Decision: This section describes our response to these forces.
Status: A decision may be “proposed” if the project stakeholders haven’t agreed or “accepted” once approved. If a later ADR changes or reverses a decision, it may be marked as “deprecated” or “superseded” on its replacement.
Consequences: This section describes the resulting context after applying the decision. All consequences should be listed here, not the “positive” ones.
A particular decision may have positive, negative, and neutral consequences, but they all affect the team and project in the future. The whole document should be one or two pages long. We will write each ADR as a conversation with a future developer. This requires a good writing style, with complete sentences organized into paragraphs.
Bullets are acceptable only for visual style, not as an excuse for writing sentence fragments. One ADR describes one significant decision for a specific project. It should affect how the rest of the project will run.
One ADR’s consequences will likely become the context for the next ADRs. This is also like Alexander’s idea of a pattern language: the large-scale responses create spaces for the smaller scale to fit into. Developers and project stakeholders can see the ADRs, even as the team composition changes. The motivation behind previous decisions is visible to everyone, present and future.
