In this post, I discuss my thoughts on the docs-as-code approach to creating documentation. This article is for technical writers, developers (with any degree of experience), project managers, DevOps and DocOps engineers, and anybody else working with or is interested in the developer documentation.

In this article, we discuss:

1. What is docs-as-code?
2. Why docs-as-code?
3. Implementing docs-as-code
4. Challenges you might face while implementing docs-as-code
5. Conclusion

1. What is docs-as-code?

Docs-as-code is an approach in which you create documentation using the same tools, technologies, and processes that developers use to create code. So what meaning does this hold to a technical writer?

• The content format: Using markdown to write content instead of the traditional HTML, CSS, and JS (various organizations are now transitioning to MDX, which is a combination of markdown and react; however, that’s a topic for another post ;) ).
• Version control: Keeping documentation up to date on GitHub or any other version control service you use to keep your code up to date.
• Doc reviews same as code reviews: Following the code review process for document review.
• Automate validation: In docs-as-code, validation scripts test the docs against fundamental use cases such as broken links (DocOps similar to DevOps).
• Managing docs using the same tools as engineers: Using tools such as JIRA to manage doc issues, report on the progress of documents at regular intervals, and show demos.

2. Why docs-as-code?

Unlike the traditional technique, where documentation is frequently the final step, the docs-as-code strategy tightly integrates documentation with the product and product development, making it an inevitable component of product release. The docs-as-code approach bridges the gap between documentation and the product, which benefits both users and the technical writers.

3. Implementing docs-as-code

Firstly, let us try and understand the code workflow.

For instance, consider that a developer is working on a feature. Let us assume that they use GitHub for version control.

1. The developer forks the current state of a working repo on GitHub, where the primary product’s code is stored.
2. After coding, the developer creates a change request and commits the changes into GitHub for review. At this stage, a few automatic validators run to detect possible errors.
3. The developer fixes the bugs (if any) and updates the change request.
4. The code is then merged into the working repository and deployed in the upcoming release.

Merging documentation alongside the code workflow

For instance, consider a technical writer working on the documentation of a feature. Let us assume that they use GitHub for version control.

1. The technical writer creates a fork of the current state of a working repository where the documentation is stored.
2. After completing the document, the technical writer creates a change request and commits the document into GitHub for review. At this stage, a few automatic validators run to detect possible errors such as broken links, typos, style-guide violations, and so on.
3. The technical writer fixes the bugs (if any) and updates the change request.
4. The document is then merged into the working repository and may either be published to the documentation site immediately or planned to correspond with the feature release.

4. Challenges you might face while implementing docs-as-code

The docs-as-code strategy does not offer a specific solution to the typical document requirements such as localization, content re-use, authentication, publishing docs as PDF, and other features that HATs offer.

5. Conclusion

All of this said and done, tools and techniques that we use to create documentation vary greatly depending on needs and use cases, both personal and organizational. The secret sauce to developing good documentation is always user research, clear language, discoverability, clarity, and correctness, as well as the quality of the review process that it goes through.

References

• https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html
• https://pronovix.com/blog/cicd-and-docs-code-workflow
• https://www.writethedocs.org/guide/docs-as-code/
• https://www.youtube.com/watch?v=Z3e_38WS-2Q&t=2656s
• https://www.youtube.com/watch?v=EnB8GtPuauw