Documenting Decisions in Agile
Begin documenting before you begin developing. Accept (some) Repetition In Documentation. Structure content to help readers identify and skip over concepts they already understand. Examples and tutorials in content. Incorrect documentation is worse than missing documentation. Store sources as close as possible to the code which they document.
Give developers systems that allow them to make documentation and code changes. Ensure that all the publications in the body of documentation can answer all questions the user is likely to have. There are a lot of nebulous problems in communication inside organizations. Documentation could be fancier, and teams to neglected. Start small with something that you can nail. Focus on small, essential projects to progress with documentation efforts for the organization. Solve the documentation issue around a single internal project in the Engineering organization. Define a simple outline to follow and assign a point of contact to track execution and progress. Schedule a weekly standing meeting to keep track of the progress along all the stages. Content should be ordered to cover prerequisite concepts first. 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. Documentation is writing down what we do right. Have a wiki as your central base. Have a document repository where to put your documents, diagrams, etc.
Working software over comprehensive documentation. Agile suggests working with software over documentation because it presents development results. Yet, the onboarding process requires formal documentation to ramp up people to the team’s culture faster. Focus on the code. Writing code is more productive, but documentation about the team’s past and decisions is essential. Formalized requirements processes can map the concept from the business into the code and vice versa. Let’s keep the software working.
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.
Maintain open and transparent communication inside and outside of our teams. Allow us to share our thinking and methods with our stakeholders. Not all decisions will be made at once, nor will they be done when the project begins. ADR describes a set of forces and a single decision responding to those forces. (Though the findings are not patterns, they share the characteristic balancing of energies.) The decision is central so that specific forces may appear in many ADRs. Keep ADRs where it is best convenient for the team. It might be the project’s repository or its repository under doc/arch/adr-NNN.md. Use lightweight text formatting language like Markdown or Textile. ADRs will be numbered. Use a format with a few parts, so each document is easy to digest. ADRs have names that are noun phrases. e.g., “ADR 1: Deployment on Ruby on Rails 7.0.10” or “ADR 9: RabbitMQ for Inter-Service Pub-Sub Communication”.
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. Bite-sized pieces are more straightforward for everybody to consume. It may not be good if the context changes, and the decision should be revisited.
