I would like to argue that developers and development teams deserve and need good documentation. When such documentation exists – it makes the onboarding process easier and faster, it helps teams be more agile and transfer knowledge when needed, and it helps you in those cases where you need someone to understand something in the moment – for example, when you have a bug affecting production and you must find a solution.
While high-quality and up-to-date documentation is an essential component of software development, developers today lack efficient code documentation and relevant tools. This affects the way they onboard new projects, the time it takes for them to make meaningful contributions, and the quality of their releases.
In this blog post, I will introduce the methodology of Continuous Documentation. Continuous Documentation calls for creating and maintaining code documentation in a way that incorporates it into the normal development workflow. You need to treat documentation as you treat other crucial parts of your development workflow – like tests, or the code itself.
But first, let’s understand the challenges in documenting code today.
This is part of a series of articles about what is Documentation.
Challenges posed by current practices
Many challenges are posed by the documentation practices common today:
1. The can kicked down the road
Without Continuous Documentation, documentation is created on rare occasions. It can happen for example, when many new hires are joining together and it is clear the team would spend a lot of time helping them onboard, and usually when it is already too late – when we find out that transferring knowledge is very difficult. Creating documentation this way is hard and ineffective. Even When you need to document something you yourself have implemented a long time ago – it’s way more difficult to do so than documenting when it’s fresh. Of course, the problem worsens when the most relevant person to document something is simply no longer available to document it, for example if they have left the team.
This is a similar pattern to how developers used to create tests, before continuous integration. That is, creating tests after implementing a lot of code, rather in continuous, gradual steps.
2. The code evolves, leading to obsolete docs
So when engineering teams get to documentation it then often happens in sprints. In these sprints, many projects and parts of the code are documented at once. As a result, documentation is fresh and relevant at the time of the sprint, but quickly becomes stale. After a few weeks or months, developers attempting to learn the code from the documentation quickly find out it is no longer up-to-date, and thus lose trust in the documentation and no longer rely on it.
3. Effort vs lack of time
With current tools, creating high-quality documentation requires a lot of time and effort. This becomes ever more true as systems get more complex – Documenting multiple services that depend on each other and are constantly getting updated is a resource-intensive process. Therefore, many engineering teams don’t perform it at all. Writing meaningful documentation takes thought and time, and teams may not find that time given all the other tasks they have at hand.
Learn more in our detailed guide to continuous documentation.
Enter: Continuous Documentation
Continuous documentation is the process of creating and updating documentation incrementally and as part of the development workflow, ensuring it is in sync with the codebase.
I argue for three main principles. Continuous Documentation means that the documentation is:
- Code-Coupled
- Always up-to-date
- Created when best
Code-coupled documentation
This means documentation that explicitly references parts of the code. For example, including code snippets, names of functions or variables, file paths and other explicit reference to the code, within the documents.
This kind of documentation gives a similar experience to getting a first-hand explanation from the person who has originally written the code. Making the documentation coupled with the codebase enables making sure the document is up-to-date, and also to easily find the document. All of these things are vital in order to make Continuous Documentation an actual practice rather than an ideal we strive for.
Always up to date
Continuously verifying documentation means making sure that the current state of the documentation matches the current state of the codebase, as the code evolves.
By continuously verifying documentation, developers can trust their documentation and know that what’s written there is still relevant and valid, or at least get a clear indication that a certain part of it is no longer valid. In order to keep the docs in sync with the codebase, existing documentation needs to be checked against the current state of the code continuously and automatically. In this sense, Continuous Documentation is very much like continuous integration – it makes sure the documentation is always correct, similar to verifying that all the tests pass. This could be done on every commit, push, merge, or any other version control mechanism.
Learn more in our detailed guide to documentation strategies.
Created when best
Continuously creating documentation means that documentation is written not as an aftermath, but when it makes sense.
For example, when a big feature has been completed, or when a crucial bug has been fixed in a way other contributors to the code would need to know or understand. This makes creating documentation much easier – developers write the documentation when everything is still fresh and clear in their minds. This could be achieved in many ways – either with automated suggestions by tools, or by forming a team habit to create documentation after every sprint.
Bottom line
Back to square one: developers deserve good documentation. More specifically – developers deserve practical, code-coupled, high-quality, up-to-date documentation that allows them to quickly understand code they are not familiar with. Documentation of this sort speeds up development and allows agility for dev teams, as developers can quickly shift between various tasks.
We must change the way we create and consume documentation, and follow the principles of Continuous Documentation: creating code-coupled documentation in tandem with fresh ideas and ensuring it is up to date.
I hope this approach will inspire you to rethink the way your team, and developers in general, share knowledge with each other.
…
To get started with this methodology, check out Swimm, the first tool that enables practicing Continuous Documentation for development teams.
And to see Swimm in action, sign up for a Swimm demo.
