In part 8 of our series on twelve-factor DevOps, we examine the importance of documentation. Encompassing far more than simply consciously-written user guides and developer notes, proper documentation is a living source of data about your products.
Factor 8: Documentation
Documentation is one of the harder problems to solve. One of the biggest concerns with documentation is that it often takes the form of binary files like Word documents or PDFs, and those take time to generate and don’t play nicely with where developers do their work. From what to write down to where it’s saved, people argue about documents all the time and tend to forget about them because new stories are in the backlog. Left undone, documentation can be a major source of tech debt. Properly handled, documentation improves your ability to onboard team members, maintain & support the product, and convey business value.
A 12-factor DevOps culture embraces documentation as code in addition to documentation within the code. This can be implemented with tools such as Terraform-docs, Sphinx, and Doxygen. Integrating such these tools into your pipeline results in consistent documentation that lives with the code itself.
Infrastructure and configuration management software tend to be self-documenting. A Terraform plan defines your overall environment in excruciating detail, listing the existence of and settings for every resource. Ansible playbooks and Puppet manifests explain how the resources are configured and what is present where. Finally, tools like DataDog and Nagios can automatically produce network diagrams from the resources that they monitor.
Logs, monitoring data, and alerts must be considered crucial sources of documentation. Application and infrastructure logs provide feedback to improve the product. If you are aware that end-users routinely encounter a specific 404 error or cause an exception by performing a given action, you can implement changes in the code to prevent those and improve the user experience. Monitoring data and alerts foster stability and reliability by highlighting chokepoints and resource constraints, enabling you to proactively make adjustments. Aggregating all these logs into a single place is a win across the team. Security gets audit trails, operations has concrete data about environmental and software health, developers learn where to focus tech-debt efforts, and the business stakeholders can point to the robustness of the product.
Some manual documentation will always exist; product goals, user stories, and swagger documents require human input. But by embracing the first of the twelve factors (Automate) for your documentation, you enable people to use it deliberately and more frequently, and in more proactive ways.
