Docs-as-Code and DevOps Success

Why is Documentation so Bad?

Everyone in software talks about embracing DevOps. They want to achieve the high up times, low error rates, and engineer satisfaction and engagement levels typical of elite DevOps teams. Too often the reality is these dreams crash against poor fundamental practices in other areas — inconsistent production and non-production environments, inadequate monitoring and logging, incomplete code reviews, manual practices especially testing, and poor documentation.

Of these, documentation quality would seem like the easiest thing to fix. How can something so essential be so often wrong? Yet we all hear statements like this all the time:

● “I can’t believe we’re still using these old instructions to set up the development environment. I’ve spent the past two hours trying to get everything working, and it would have been a lot easier if the documentation had been up to date.” (software engineer)

● “I’m not sure how this feature is supposed to work. The documentation says one thing, but when I look at the code, it looks like it’s doing something else entirely. Can someone clarify?” (product owner)

● “We’re getting a lot of support calls about this feature that we thought was working. It turns out the documentation doesn’t match the actual implementation. We need to fix this ASAP.” (product owner)

● “It’s really frustrating trying to guide the team when the documentation is incomplete and out of date. I don’t have all the information I need to make informed decisions or plan our sprints effectively.” (scrum master)

● “The current docs are out of date but I don’t want to delete them because they may be useful. So I’ll just create more…” (everyone)

Software engineers, product owners, and scrum masters all agree: incomplete and out of date documentation is often a major barrier to achieving a successful DevOps transformation. It leads to confusion, delays, and wasted effort as developers try to understand and work with poorly documented systems and code that do not accurately reflect the current state of the project.

One of the first steps in a DevOps transformation is to increase Deployment Frequency while not increasing Change Failure Rate (deploy more often while not increasing production defects). Deploying more frequently requires less wasted time by everyone. Having to ask whether the code or the documentation reflects intended behavior wastes time. Following outdated practices and procedures based on out-of-date documentation wastes time. It wastes time when new team members can’t get up to speed because they lack the historical knowledge that makes up for gaps in documentation.

Poor documentation can ruin a DevOps transformation. Effective documentation is essential for team collaboration and the successful development and maintenance of software. Why is it so rarely available?

Docs-as-Code Practice: Why Not Just Hire More Tech Writers?

Docs-as-code can help. Docs-as-code is an approach to documentation in which documentation is treated as a first-class citizen in the development process, as important as the code itself. Under a Docs-as-Code scheme the documentation is stored in the same version control system as the code, follows the same workflows as the code itself (including code review), and is built and deployed using the similar tools and pipelines code. There is no separate process for approving documentation, no separate pipeline for publishing it. The documentation is treated just like code.

Treating documentation just like code is why Docs-as-Code works, why it is relatively easy to implement and why it is preferable to writing and managing documentation separately from code. By treating documentation as code, teams can use the same tools and processes they use for development to manage and maintain their documentation. This can help ensure that the documentation stays current and accurate as the codebase evolves.

When there is a separate process for producing documentation, then documentation tends to become less important than the code itself. In the rush to deliver features the separate documentation process will be skipped, creating a debt that is rarely paid back. This is exactly what happens in companies around the world.

In practice, these are the key principles of Docs-as-Code:

● Documentation is stored in the same version control system as the code.

● Documentation follows the same workflows as code (including being reviewed with the code in code reviews).

● Documentation is built and deployed using the same pipeline and similar tools as the code.

● Overall, documentation is treated as a first-class citizen in the development process, equal to code.

By following these principles, teams ensure that their documentation stays up to date and accurate as the codebase evolves.

Docs-as-Code Tooling

There are a variety of tools available for supporting Docs-as-Code practices. Some common tools include:

● Version control systems: These are used to store and track changes to documentation, just as they are used for code. Most often that source control system will be Git in some form, but the important point is documents should be stored in the same repository as the source code they describe. We recommend Git, but if you use Subversion, Mercurial or something else that works too.

● Documentation generators: These tools are used to automatically generate documentation from source code or other sources. Examples include Doxygen, Javadoc, and Sphinx.

● Static site generators: These tools are used to build static HTML documentation sites from source files written in a markup language such as Markdown or reStructuredText. Examples include Jekyll, Hugo, and MkDocs. This lets you publish your documentation in one common easy to reach location. Or you can just read it in your source control tool.

● Collaboration and review tools: These tools are used to facilitate collaboration on documentation and facilitate the review process. Examples include GitHub or GitLab. It is important that documentation is reviewed at the same time as the code it describes, ideally using the same tooling.

● Continuous integration and delivery (CI/CD) tools: These tools are used to automate the build, test, and deployment of code and documentation. Examples include Jenkins, Travis CI, CircleCI, Gitlab. What is important is that once a PR or MR is approved, both code and documentation are released at the same time and identified by the same version identifier.

A typical Docs-as-Code workflow might look like this:

● Merge pull request in Github ( code and documentation merged together)

● Azure Pipeline Integration automatically kicks off

● Run MKDocs compiler

○ converts markdown to HTML

○ rebuilds entire MKDocs site

○ deploys the rebuilt site.

Total time required should be minutes.

Overall, the choice of tools will depend on the needs and preferences of the team, as well as the size and complexity of the project. Often the best recommendation is to adapt the tools you already use to Docs-as-Code. It is the practice of treating documentation just like code that is important, not so much the tooling itself.

Docs-as-Code vs DevOps: Similarities and Differences

DevOps and Docs-as-code follow similar workflows for managing and maintaining code and documentation. They are very similar and complementary to one another.

In both cases, the goal is to make it easier to collaborate, coordinate, and iterate on development efforts. By treating documentation and code in the same way, teams can streamline their workflows and make it easier to coordinate efforts between different disciplines and roles.

Both Docs-as-Code and DevOps use automation and tools to streamline and improve the development process. This keeps deployments small and frequent, which is proven to improve software quality. Each practice uses version control systems to track changes and CI/CD tooling to automate the build, test, and deployment process. A Docs-as-Code practice may also use documentation generators to automatically generate documentation from markup text, as well as static site generators to build documentation websites.

The obvious difference between Docs-as-Code and DevOps is focus: Docs-as-Code is primarily focused on improving the management and maintenance of documentation, while DevOps is focused on improving the collaboration and coordination between development and operations. However, the two approaches are closely related and can be used together to improve the overall development process.

Docs-as-code supports a DevOps transformation by treating documentation as a first-class citizen in the development process and following the same workflows as code. When a team adopts DevOps techniques and their Deployment Frequency begins to escalate it is common for manual steps in the process to act as a barrier to further progress. A typical barrier is a reliance on manual testing, another is depending on manually (and inaccurately) produced documentation.

Implementing Docs-as-Code

There are a few strategies you can use to keep documentation up to date on a software project:

1. Make documentation a part of your development process: This means that as you work on new features or make changes to the codebase, you should also update the relevant documentation. This can help ensure that the documentation stays current as the codebase evolves.
2. Use the same version control system for your documentation as your code. By storing your documentation in a version control system, you can track changes and roll back if necessary. This is especially useful when multiple people are working on the documentation.
3. If there is special tooling necessary to generate documentation and websites, then integrate that tooling with your CI/CD pipeline.
4. Establish a documentation review process that is integrated with code reviews. Remember, code and documentation for any change are equally important. They should be reviewed at the same time.

Overall, the key is to make documentation maintenance a priority and to establish processes and systems that support ongoing documentation efforts.

Expected Outcomes from Docs-as-Code

You can expect the following when implementing Docs-as-Code practices:

● Improved documentation quality: By treating documentation as code and following the same workflows as development, teams can ensure that their documentation is accurate, up to date, and follows best practices.

● Easier documentation maintenance: By storing documentation in the same version control system as the code, teams can track changes and roll back if necessary. This makes it easier to keep documentation up to date as the codebase evolves.

● Greater collaboration: By following the same workflows as development, teams can encourage collaboration on documentation and ensure that everyone is on the same page.

● Enhanced visibility: By treating documentation as a first-class citizen in the development process, teams can make it more visible and ensure that it gets the attention it deserves.

● Better alignment with development processes: By using the same tools and processes for documentation as for development, teams can streamline their workflows and make it easier to coordinate efforts.

Overall, using Docs-as-Code practices can help teams create high-quality documentation that is easy to maintain and stays up to date as the codebase evolves. This can improve collaboration, enhance visibility, and better align documentation with development processes.

An Engineering Culture that Values Documentation

If your engineering teams simply do not value documentation it will be hard to gather momentum around implementing Docs-as-Code. Here are a few strategies you can use to develop an engineering culture that values documentation:

● Make documentation a priority. This might involve setting goals for documentation coverage, incorporating documentation into the development workflow, or providing resources for documentation efforts. Make sure documentation is given the same level of attention and importance as other aspects of the development process.

● Encourage collaboration. Like peer programming, having team members to work together on documentation helps share knowledge and best practices. A document review process would be part of a typical pipeline, but consider creating a documentation guild or community of practice.

● Training. Let’s face it, many engineers are not great writers. An area of growth for them could be improving their documentation skills. This might involve providing training or resources for learning or creating opportunities for team members to share their knowledge with others.

● Make documentation visible. If you are going to make the effort to adopt Docs-as-Code then you should also make sure that documentation is easy to access and find. It is a good idea to include links to documentation in the code base itself.

By taking these steps, you can help create an environment where documentation is seen as a first-class product of the development process.

Summary

Overall, the specific needs, skills, and resources of your team will determine whether or not to use Docs-as-Code practices. However, if you choose not to use Docs-as-Code you will still need a practice that keeps your documentation up to date for both producers and users of the software. For teams with a need to manage and maintain detailed, up-to-date documentation, Docs-as-Code can be a powerful approach and the right tool for the job.

Building Software that Thrives on Change

In Sourced Group’s experience engineering organizations can be broken down into three groups:

Base-level engineering organizations employ many manual processes. Performance declines rapidly under a limited amount of change or load. Their capacity for improvement is small and they can only recover to baseline performance with extreme difficulty.

Effective engineering organizations produce good quality software while enduring a moderate amount of change or load. If stress exceeds a certain threshold performance rapidly declines. These organizations use some automated processes while still depending on manual work for important tasks. Their capacity for improvement is modest and they can recover to baseline performance with moderate difficulty.

Elite engineering organizations grow stronger the more change or load is applied to them, in the same way the human body grows stronger through rigorous exercise. They actively seek to learn from mistakes and incorporate those learnings into future work, often embracing cloud infrastructure and cloud-native architectures. These organizations depend heavily on automation to increase quality while reducing cognitive load on teams and individuals. Their capacity for improvement is great and under stress they can recover to baseline performance with relative ease.

Getting Agile and DevOps transformations right is critical to becoming an elite engineering organization. If you’d like to discuss the concepts included in this article, please reach out to the author at mryan@kenzan.com.

Michael Ryan is Managing Principal Consultant and Head of Architecture at Sourced Group. If you’d like to discuss these concepts further please reach out to the author at mike.ryan@sourcedgroup.com

Author’s linkedin page: https://www.linkedin.com/in/michael-james-ryan/