What is “Docs as Code?”

“Docs as Code” means managing technical documentation in the same way developers would manage their code. Let me explain in simple terms what a typical software development process is. First, developers write code using a text editor and commit it to the version control system to share it with members and receive any version changes. Then, the lead developer reviews and merges the code. Finally, they build and release the finalized code. Technical writers can apply this software development process to technical documentation using the same tools as developers.

Docs as Code tools

You will need the following components for technical documentation:

Text files: Files where your contents exist. It is common to write the content in Markdown format.
Text editor: Software used to write code/content, equivalent to Microsoft Word in the non-dev world. Atom or Sublime is recommended for beginners.
Version control and collaboration tool: The system that will be used to track the changes in the files. Git is currently the most popular.
Static site generator: A static site generator is necessary for converting text files into HTML format for publishing. Jekyll or Hugo are commonly used for this operation.

In practice: How it works with Docs as Code tools

Here is the common process for Docs as Code:

Write your content in a plain text format (Markdown, etc.) using a text editor.
Commit the content and its changes to Git.
Your reviewer will find your commit and merge your branch if it is accepted.
Put the final text file in the static site generator to change your content into HTML format.
When the review processes are completed, you can deploy the docs to the target, cloud, or server.

Why Docs as Code is rewarding for technical writers

Taking a non-dev role in a software company is challenging but beneficial at the same time.

Follow the same review process as the developers using Git

Developers use the Git system to submit their code and changes, which are reviewed by their co-workers before being accepted to be merged into the master code branch by the lead engineer. This is the key review process that helps maintain the quality and uniformity of the code for the product. The same goes for technical writers. With Docs as Code, technical writers do not need to ask for explanations or alert everyone to changes, but can instead catch modifications through the code review process in Git.

Easy sync with the product and version tracking

Using collaborative documentation editors such as wikis or Confluence to track versions and contents for every update takes time and effort in practice. But by having Docs as Code, we can have the documentation live right along with the code, and it makes technical contents sync with the product more easily compared to an independent documentation system.

Writers and developers integrated within the product team

Using the same tools as developers helps the team work more efficiently. If your product is just a simple version of hosted web pages, then this might not sound attractive. But highly complex products need a large amount of extensive documentation. This eventually requires developers and writers to not only contribute to documentation cooperatively, but also review each other’s changes. Docs as Code will help both parties feel like they are on the same team.

Professional growth

The acquisition of these skills will be of greatest benefit to you as a writer in the long run. If there are writers who write content directly as part of the product codes and writers who write well, who would you hire if you were the company owner?

Summary

Are you worried about learning Docs as Code tools? The effort required to learn these tools is much less than learning a new human language. (And I know most technical writers are geniuses at learning new languages). I am confident that the results will provide you with more than just personal career growth.

Interested in being a writer in the IT field? Find more articles here, Certifications for Technical Writers Transitioning Into the (IT) Field.