Docs-as-code: A Brief Introduction

Introduction

There is a need to have structured, organized documentation in place. Just like in code, where there is a codebase and there are processes in place to maintain that code. That is the same approach being applied in the documentation. This article will briefly introduce how documentation is organized as code and some of the key points about it.

What is Docs-as-Code?
Why Docs-as-Code?
Benefits of Docs-as-Code
Setting up Docs-as-Code
Best practices of Docs-as-Code
Conclusion
Resources

What is Docs-as-code?

Docs-as-code means “documentation as code.” It is an approach where documentation teams create and manage documentation using the same tools and workflows as engineers.

This approach aims to make documentation follow the same process as software development. It is used to document, collaborate, and maintain software documentation.

Why Docs-as-code?

Before Docs-as-Code, documentation was scattered across many platforms, on internal wikis, and in content management systems. This made content publishing an uphill task.

That was not all; it was hard to get developers to share their knowledge. especially on building APIs and other products that involved their expertise.

It makes it easier for developers to contribute to the docs while building applications.

Docs-as-code aims to unify the source of documentation. instead of having scattered content. It unifies all the content so teams can easily find it and make their contributions.

Docs-as-code uses tools that track changes and make updates. Also running tests before deployment. It saves developers and writers alike the hassle of using traditional publishing systems.

Benefits of Docs-as-Code

Proper documentation

The documentation team may not know much about the product or API. With Docs-as-Code, development teams can contribute their knowledge in the docs. Then, the documentation team can develop it to the right standard.

Improved documentation maintenance

Docs-as-Code has improved the documentation maintenance process. Using version control makes it easier to update documentation alongside code changes. Technical writers can easily review and integrate changes into the main documentation. This makes the documentation up-to-date and accurate.

Collaboration

Docs-as-Code breeds collaboration among teams. as developers get to work with technical writers to create documentation. They would write a draft of the product, and the documentation team would complete the work. Also, product managers and QA testers get to review and test the documentation, each contributing their own quota to it. It promotes communication and cooperation among the teams.

Automation

Another benefit of Docs-as-Code is that you can automate the process. For example, when you are running automated checks for grammatical errors and security checks. This is normally done during the deployment process. Before the deployment is complete, you would carry out automated checks to inspect the changes and determine whether to merge them. Automation speeds up the process, making it easier to integrate changes.

Versioning

Using version control on documentation makes it possible to track changes with version histories. You could easily roll back changes or introduce a new version. Because of the version control process in doc-as-code, changes are recorded. Anyone can introduce new features to the docs, and they could maintain the features via the version control system in place.

Setting up Docs-as-Code

To use Docs-as-Code, you need tools like:

An IDE
static site generators (Sphinx, Hugo)
hosting platform (GitHub Pages, Netlify)
CI/CD pipeline (Jenkins, GitHub Actions)
git and an online git repository like GitHub or BitBucket.

An IDE (Integrated Development Environment)

Docs-as-code is popularly written in markdown or latex. Some IDEs provide support for markdown, such as VS Code, Sublime Text, and so on. Any of these IDes could serve as a development environment for doc-as-code.

Static Site Generators (SSG)

Static site generators are tools that render a couple of HTML files on a website. SSGs generate these texts beforehand, so when you install the SSG on your system, it displays them in a browser. Examples of static site generators are Sphinx, Docusaurus, and Hugo. Static site generators usually work with a programming language; for instance, Sphinx uses Python while Docusaurus uses JavaScript.

Hosting Platform

Netlify and GitHub Pages are some of the popular hosting platforms where you can host documentation. But you can host these SSGs on any other platform of your choice.

CI/CD pipeline

This means continuous integration and continuous deployment. As the name implies, these tools are used to make updates whenever developers make changes to the documentation. They automate the process of checking the documentation for errors and other mistakes that could affect the primary site when you deploy the changes.

Some examples of pipelines are GitHub Actions, Jenkins, and so on.

Git and an online git repository

Git provides versioning and tracking of changes. With git, you could also revert changes that could affect the site in production. You could use any git hosting platform of your choice, like GitHub, BitBucket, or GitLab, to run git operations.

Best practices for writing documentation as code

Regular maintenance

You should maintain your documentation and make updates within a specific period. probably every three months to cover all the changes made during that period.

Removing outdated documentation

Documentations usually have a time lapse before the information in them expires. It could be because of software updates on the application or partner vendors’ applications. Hence the need to remove all outdated content from it.

Be clear, concise, and consistent

Add comments when necessary and use the proper headings and writing style for your audience. Keep each page crisp and well-detailed. Do not overload your readers with too many words on a page. Always break it up and be consistent in your writing style.

Add helpful tools to the CI/CD pipeline

Embed grammatical tools in the automation process for CI/CD. To avoid any errors that could be in the documentation. Enforce security too; you need your documentation to be safe from potential attacks. If your documentation is open source, then you should ensure that you apply security to the CI/CD pipeline to eliminate all likely attacks.

Conclusion

Docs-as-code is a concept of making and maintaining documentation as code. It came to be due to constraints from unorganized documentation. Docs-as-code aims to solve problems and make documentation simple and smooth.

Resources

Docs-as-code — WriteTheDocs

Docs-as-code tools | Documenting APIs

Blog