Continuous Documentation In A CI/CD World

Continuous documentation is the process of creating and maintaining code documentation incrementally throughout a project in a way that seamlessly incorporates it into the development workflow. It is a key part of improving reliability within an organization.

It’s not just new features that need to be documented – anything useful from bug fixes, to how to get started using the code should be documented. It should also be updated frequently to ensure that it stays relevant.

Although continuous documentation is viewed as a core part of Agile development, it is still only implemented by some organizations.

In this article, we’ll discuss the importance of documentation in a CI (continuous integration) and CD (continuous delivery) world.

Why is continuous documentation important in a CI/CD world?

Continuous documentation is so important in a CI/CD workflow because it helps other developers easily understand how to use your software. This saves time and makes it more efficient for teams to transfer knowledge when they need to.

This can make onboarding significantly easier. According to research by Swimm, it takes an average of three to nine months for new software developers to ‘ramp up’ after joining a team. Having a thorough documentation system in place can significantly reduce this time.

The 3 key principles of continuous documentation

1. The documentation should directly reference the part of the code it is referring to

This makes the documentation easier to find, and also helps to make sure that it is up to date.

2. The documentation should evolve at the same rate as the code

Keeping documentation up to date means that developers will be able to trust it, and makes them more likely to utilize it when they need to.

3. Developers should write documentation when it is still fresh in their minds

This is more efficient because it means that less time will be wasted going back and trying to remember what should be included. This can be done by creating a habit as a team to regularly create documentation after each sprint, or by downloading a tool that automatically reminds developers to create documentation.

Challenges posed by current documenting

Despite the importance of documentation, it is often put on the backburner by developers and organizations for several reasons:

• Documentation is not viewed as a priority by organizations: As a result, it is often created only on specific occasions – such as when a group of new hires has joined the organization and the team is trying to bring them up to speed quickly. However, onboarding new employees and writing documentation are both challenging enough tasks by themselves, and trying to do both at the same time means the process is often rushed.
• Documentation is often viewed as a chore that takes time away from the primary task of writing code: This means that the task of writing documentation is often passed off to interns who are not in the best position to write it.
• Documentation updates often happen in sprints that occur less frequently than the code is updated: This means that documentation can quickly end up obsolete, which leads to developers losing trust in it and deciding not to use it.
• As the codebase gets more complex, so does the documentation: As a result, it ends up taking more time to write and update, which results in many organizations deciding to abandon it altogether.

Continuous documentation and culture change

For continuous documentation to be successful, it requires a culture change. If an organization has never valued the process of writing documentation before, then it is unrealistic to expect this to change overnight.

As it stands, most organizations still devalue the process of writing documentation – nobody wants to do it, and many developers don’t even know how to write documentation properly because they have never been taught.

Before anything else, teams should make sure that they get a functioning documentation system in place. Then, they can start to form a habit of contributing to the documentation more, and shortening the delivery window. This is a gradual process that can take a long time to implement.

Where to begin with CI/CD documentation

CI/CD documentation is a continuous process that can take a long time to implement. To get started, organizations should come up with a gradual plan.

For most teams, it makes sense to start by creating documentation that will have the biggest impact in the short term.

Organizations should learn to view documentation debt as an essential part of a team’s overall technical debt so that it is prioritized instead of consistently being pushed back as an afterthought. This can be done by creating separate tickets for documentation and making sure they are addressed sufficiently.

Once the team has made this a habit, then the team should make sure that they prioritize incorporating documentation into each sprint moving forward. This will help to ensure that documentation is written while the code and the feedback is still fresh in developers’ minds, which will make the process significantly more efficient.

Where does continuous documentation live?

Code documentation should be as close to the code as possible. For example, if you’re using GitHub, you should include it in your commit messages. This helps to make sure that it is easily accessible to those who need it.

Continuous documentation and improving reliability

Continuous documentation helps developers to quickly understand code that they are not familiar with and makes it easier for them to get up to speed with a new project. This helps to speed up development, and also reduces confusion and makes it significantly easier for developers to switch their focus between tasks.

Continuous documentation also allows teams to think more deeply about how they share information. This helps to improve communication between team members, which ultimately leads to helping them to build more reliable software.