Continuous integration and automation are key aspects of high-performing DevOps environments. Teams work hard to create pipelines that do most of the repetitive work automatically, reducing the cognitive load of software and infrastructure engineers. And yet, we do not do this with documentation, the thing that helps new developers onboard quickly, help teams understand what architecture and design decisions were made in the past, and help users actually use our product.
Passing the hot potato around
Even though documenting is a core agile practice, it is repressed by the constant pressure of delivering business value to stakeholders quickly.
As many fast-scaling startups or large enterprises have experienced first hand, there is a strong relationship between good onboarding documentation and a developer’s productivity. This demonstrably manifests as:
- Documented design decisions and high-quality, secure software,
- Documentation covering 100% of the code base’s code, and clearly-documented technical debt,
- Up-to-date, accurate and complete user guides and a low customer / user support load
Yet, developers and organizations pass the hot potato around, reluctant to invest in documentation. It’s a can kicked down the road, and procrastination and inevitable context switching reduces the resolution and quality of the documentation when (or even if) written down eventually. Documentation handled with this much disdain will forever be outdated, inaccurate, incomplete and, crucially, a chore.
Continuous Documentation is our second brain
Enter continuous documentation, the practice of updating documentation in lockstep with updating the code base. The continuous documentation pipeline builds and updates documentation incrementally, keeping it in sync with the code base, corrects inconsistencies and inaccuracies automatically and creates visibility with documentation coverage issues for a given code base.
Continuous Documentation automates the heavy lifting and reduces the toil that distracts teams from their core business: software development. By implementing documentation as code, documentation becomes machine readable, testable and scannable. By treating it as code and placing it in version-controlled repositories alongside the associated source code, it is strongly coupled with codebase itself and has strong cohesion with the code.
Continuous Documentation reduces a team’s cognitive load, leading to less errors and inconsistencies. It creates a positive feedback loop, which increases documentation coverage and quality incrementally with each commit and sprint. It shows teams which parts of the code bases have good documentation, and where the blind spots are. By creating visibility, work to increase documentation coverage or quality can be planned as user stories in scrum sprints. It becomes a measurable unit of work, planned-for instead of rushed or forgotten.
Microservices can make documentation debt soar
The great thing about microservices is each team can do things differently. Some teams might use a different thread library, while others might use completely different compiler flags. Some might use different languages entirely. These nuances tend to grow and become chasms that engineers have to leap repeatedly, every time they onboard to a new team and code base. For cloud-native developers, great documentation isn’t just a requirement for new hires – it’s a quality of life problem for everyone.
Placing documentation checks within the CI/CD pipeline expedites the dev loop because developers spend more time writing business code than they do researching what they need to know in order to get their jobs done.
As we develop our CLI tools for Swimm, we’re constantly thinking about ways to make CI systems increasingly aware of not only how much code is covered, but also how relevant it remains as the code base changes. Developers deserve modern, functional, agreeable documentation control systems, and that’s what we’re building.
*** Learn more about Swimm and sign up for a 1:1 demo.
