Documentation
Overview
A production-ready component (service/website/package) is documented and understood. Documentation and organisational understanding increase developer velocity while mitigating organisational sprawl and technical debt. This document can somewhat bleed into our production-ready microservice checklist.
Poor documentation of dependencies and internal tools slows developers down and affects their ability to make their own services production-ready. It prevents them from using dependencies and internal tools correctly and wastes countless engineering hours, because sometimes the only way to figure out what a service or tool does (without proper documentation) is to reverse-engineer it until you understand how it works.
Poor documentation of a service also hurts the productivity of the developers who are contributing to it. Without an onboarding guide, each new developer working on the service will need to start from scratch to understand how the service works. Single points of failure and problems with the service will go unnoticed until they cause an outage. New features added to the service will often miss the big picture of how the service actually works.
The goal of good, production-ready documentation is to create and maintain a centralised repository of knowledge about the service. Sharing that knowledge has two components: the bare facts about the service, and organisational understanding of what the service does and where it fits into the organisation as a whole. The problem of poor documentation can then be divided into two subproblems: lack of documentation (the facts) and lack of understanding. Solving these two subproblems requires standardising documentation for every component and putting organisational structures into place for sharing microservice understanding.
The documentation for all components in an engineering organisation should be stored in a centralised, shared, and easily accessible place. Any developer on any team should be able to find the documentation for every component without any difficulty. An internal website containing the documentation for all microservices and internal tools tends to be the best medium for this.
Components of Good Documentation
General
Thorough, updated, and centralised documentation containing all of the relevant and essential information about the microservice. Organisational understanding at the developer, team, and ecosystem levels.
The best way to accomplish this is to make the process of updating documentation part of the development workflow. This has been covered in the document around Docs like Code. If updating documentation is seen as a separate task aside from and secondary to development, then it will never get done and will become part of the technical debt of the service. To reduce technical debt, developers should be required to accompany every significant code change with an update to the documentation.
its important to note that READMEs and Code Comments Are Not Documentation!
Many developers limit the documentation of their components to a README file in their repository or to comments scattered throughout the code. While having a README is essential, and all component code should contain appropriate comments, this is not production-ready documentation and requires that developers check out and search through the code.
Description
Each components documentation should begin with a description. It should be short, sweet, and to the point.
Architecture diagram
The description of the service should be followed by an architecture diagram. This diagram should detail the architecture of the service, including its components, its endpoints, the request flow, its dependencies (both upstream and downstream), and information about any databases or caches.
Links
Documentation needs to be a centralised resource for all the information about a component. In order for this to be true, the documentation needs to contain links to the repository, a link a the dashboard for monitoring, a link to the original RFC for the component, and a link to the most recent architecture review. Any extra information about other components, technologies used by the component, that may be useful to the developer should be included in a links section of the documentation.
Onboarding and Development Guide
The purpose of an onboarding and development section is to make it easy for a new developer to onboard to the team, begin contributing code, add features to the component, and introduce new changes into the deployment pipeline.
The first part of this section should be a step-by-step guide to setting up the service. It should walk a developer through checking out the code, setting up the environment, starting the service, and verifying that the service is working correctly (including all commands or scripts that need to be run in order to accomplish this).
The second part should guide the developer through the development cycle and deployment pipeline of the service.
Request Flows, Endpoints, and Dependencies
The documentation should also contain critical information about request flows, end‐ points, and dependencies of the component.
FAQ
Having a “Frequently Asked Questions” section takes the burden of answering common questions.
There are two categories of questions that should be answered here. The first are questions that developers about the component. The second category of questions are those that come from team members.