Skip to content

Benefits

As an engineer, it took me a while to realize that the benefits of the Docs as Code approach might not be obvious to everyone. To me, it’s like why having a dishwasher is better than washing dishes by hand — once you’ve experienced the convenience, it’s hard to imagine doing it any other way! 😉

When searching for the benefits of Docs as Code, you’ll find plenty of resources online. Most focus on how it benefits software projects and their teams, which is great, but I believe anyone who writes documents (not just documentation) can benefit. I use it for letters, articles, blog posts, invoices — pretty much everything.

If you’re already familiar with the benefits of DaC, feel free to skip ahead to what I consider the key requirements for a DaC approach.

Plain Text Files

One of my favorite benefits of Docs as Code is working with plain text files. For some, this is just a means to achieve other DaC benefits, but for me, it’s a benefit in itself. Whenever I’m forced to work with Word, it doesn’t take long before I start feeling frustrated. Here’s why:

  • Clicking through menus just to add a reference (to an image, table, section, etc.) gets tedious.
  • Section links suddenly stop working without any clear reason, leaving you with broken references.
  • There’s constant confusion over whether to add empty lines between sections and other layout questions, making it hard to maintain consistency in the document.

This list could go on and on, but I’ll stop there. Let’s just say, plain text keeps things simple and avoids these headaches.

Versioning

Version Control Everything!

I mean it. Almost everything you work on should be version controlled, and in most cases, Git is the way to go. 😄

You can add a Word document to Git or any other version control system you use, but have you ever tried navigating through commits for a Word file? While Word does have a comparison tool, it's far from convenient. It takes ages to load, and scrolling through a list of changes is a real challenge.

Plain text files, on the other hand, are easy to "diff". You can quickly track changes and see exactly what was modified.

Or imagine this scenario: You’ve been working on a document, and you realize that some changes belong in one commit, others in another, and more in a third. Good luck managing that easily with a Word file! With plain text, it’s no problem. 🙊.

Tip

If this sounds unfamiliar, I recommend learning about:

  • How "diffs" work with text files.
  • Best practices for using version control systems.

Merging

If you’ve ever worked with colleagues on the same Word document, you probably know how frustrating merging changes can be. Identifying what each person changed is difficult (see Versioning), and manually copying changes between documents often messes up the layout, breaks links (see Plain Text Files), or lead to a bunch of other problems 🙈.

With plain text files, merging is straightforward. Yes, conflicts can still happen, but version control tools clearly show where they are, making them much easier to resolve.

Other Benefits

A lot of smart people have written about even more Docs as Code benefits. Here are a few good starting points:

All right let's look at what I think the requirements for a Documents as Code approach are.