For docs-as-code, Git is essential

My thesis about docs-as-code: In software documentation, Git (or a similar tool) is essential. The reason: Git makes it easier for developers to participate in creating and reviewing your docs.

Git is the tool most commonly used by developers today. Developers use it to combine their efforts in a common repository. They use it to work on the same file, even when they are working on different projects. If you’re a writer, you can do the same.

Why Git is essential

Tech writers want documentation to get the same respect as the product. While that’s possible with management directives, that’s not realistic in most cases. It’s organically possible only if writers use the same tool as developers.

If your developers use a similar tool such as svn or mecurial, that works too.

Seven Reasons Why

If you’re a writer who works on software docs, you need to learn Git. Here’s why:

(Disclaimer: I used ChatGPT to come up with a list of reasons. ChatGPT included long-winded explanations, which I revised almost completely.)

1. Version control. In the central repository, you can identify what was changed, and when. With a little effort, you can “revert” to a specific point in the release, known as a “commit.”

2. Collaboration. Since everyone can have a copy of the repository on their local systems, they can work in parallel. This works equally well with developers and writers. You can make changes independently. You can then incorporate changes before you make your release.

3. Branching and merging. Even with SaaS, you may work on the current and future version of a product simultaneously. With an ordered branching structure, you can merge appropriate changes, and only those changes to one or both branches.

4. Review and quality assurance. When your audience and reviewers are developers, it helps to use their tools to review their changes. Developers review each other’s PRs (and MRs) with Git tools. If you use those tools, you’ll get more respect from your developers. More importantly, you can use the same “Single source of truth” for your code and documentation.

5. Integration with CI/CD pipelines. With CI/CD, you can automate checks with everything from HTML links to consistent wording. With CI/CD, you can automate publication of your content with every merge.

6. Traceability and accountability. Audit systems like SOC2 depend on this for every change, even in documentation.

7. Tooling. Whether you use Hugo, Docusaurus, DITA, or DocBook, you can integrate your tools with Git.

Yes, Git can be challenging. But it’s worth it!

Alternatives to Git

To repeat, Git can be challenging. Several companies do well because of the “Fear, Uncertainty, and Doubt” associated with Git. As far as I know, they all use systems which differ from code development processes.

It takes “hacks” to get developers to review documentation with such alternatives. There are many excellent writers who rely on these hacks, such as building PDFs or Google Docs for review.

If you move from PDFs or Google Docs to Git Pull Requests (or Merge Requests), it’s an adjustment. After I made the transition, I started writing my docs in text editors like vi and IDEs like vsCode. Today, I wouldn’t want to do it any other way.

Whatever hack is used, any comments and changes still have to be transcribed back to the document. And that leads to mistakes. These alternatives address some of the reasons described in this blog post.

If you have other non-technical people who review your work, you may want to consider alternatives. On the other hand, some companies require all of their people to learn Git. (I learned some of my best Git skills from a HR person at GitLab.)

I do not know all of the features of the “alternatives.” If some alternatives support developer-friendly reviews, that’s a point in their favor.

Learning about Git: personal reflections

If you’ve read my other posts, you’ll know that I participated in an excellent interactive session with Linus Torvalds(April 4, 2024). Linus is not only the person behind the Linux kernel, but he’s also the original developer of Git.

Those who know my story know that I struggled to learn Git. I had great teachers at @ForgeRock, who were patient with me. They nurtured my skills until I was able to set up dedicated branches.

Most of all, I feared merge conflicts. I learned to work through them. But that is not always the right approach.

Linus’s lesson: merge conflicts are a sign of inconsistent code practices. My interpretation: it’s also a sign of inconsistent practices in documentation. At minimum, if you’re running into conflicts while working on the same docs, you should “talk.” And you’ll see those problems only when you use Git, not any costly CMS.

A single source of truth for code and docs

For many writers, one “North Star” is to have a “single source of truth” for content. Ideally, that means you can “Write once, publish everywhere.” With Git, you can potentially take this one step further. With serious work, you can set up a single source of truth for both your code and documentation.

To some extent, that already happens with API reference docs.

When developers change code, that frequently changes what should go into documentation. Imagine a world where docs are tested with every code change. Imagine a world where CI/CD creates issues when the code samples in documentation no longer works. We already see this with link checker tools like Lychee.

With AI, will we be able to take this one step further? Will AI help us verify how-tos and tutorials?