Testing and the SDLC have evolved as a result of continuous integration and deployment becoming a popular method at organizations, but moving forward, organizations need to apply the same principles to documentation to keep developers up to speed.
This is according to the newly released Continuous Documentation Manifesto written by Omer Rosenbaum, the CTO at Swimm — a company that helps sync teams with their code.
“When a developer needs to build on, interact with, or change code someone else has written, they deserve documentation that will help them understand that code’s functionality, context, rationale, and more, without needing to reverse-engineer it, or waste time spelunking in threads and channels to find the people who might know,” Rosenbaum wrote in the book.
RELATED CONTENT: Documentation continues to be a thorn for developers
Currently, documentation is written in concentrated sprints and involving many aspects of code at once, similar how to how unit testing was implemented before. Also, as business value evolves the SDLC at an ever-increasing pace, the developers that write certain code simply don’t have the time to create high-quality documentation with their current tools, according to Rosenbaum.
This is coupled with the fact that the code is now more complex and that developers are moving between projects, teams and organizations more frequently, and they need a faster way to jump into a project.
This is where continuous documentation comes in: “to provide the tooling that allows the automated integration of documentation into development pipelines, by building and updating documentation incrementally, thereby keeping it in sync with the codebase,” according to Rosenbaum.
This can be achieved through three core principles that are described in the Continuous Documentation Manifesto:
- Always keeping it up to date – This can be done by verifying that the documentation matches the current state of the codebase continuously and automatically and then modifying it automatically or manually if it doesn’t match.
- Creating documentation when it’s best – This way, the documentation isn’t created as an afterthought and is updated every time a crucial bug has been fixed or when a big feature has been completed.
- Keeping it code-coupled – When the documentation is code-coupled, it explicitly references parts of the code and also contains or directs to the parts of the code itself so it is clear which source file and lines each document describes.
“[Code-coupled documentation] can take the reader through the journey of the code across various files, classes, and perhaps multiple repositories. In that way, the documentation can walk the reader through the code, as if they were getting a first-hand explanation from the person who had written the code originally. Its practicality could also mean that it gives a developer a step-by-step manual for processes and changes that are repeated often,” Rosenbaum added.
Coupling code with documentation also enables organizations to measure the documentation coverage that identifies which parts of the code are already covered by documentation and which ones aren’t. Finally, it enables finding the relevant code in a much faster way.
