Skip to content

DaC Is Easy

On this site, I want to debunk the myth that writing Docs as Code is difficult. In fact, it's not only easy, but often more efficient than using traditional word processors like Word. Plus, the results can look even better! 😄

Plenty of resources exist, both online and offline, that explain the benefits of the Docs as Code approach. Instead of focusing too much on those, I’ll present some key benefits but most of the time link to other resources that go into more detail. My main goal is to list common requirements for writing Docs and showcase practical solutions to meet them.

The idea is simple: we’ll start with a single source file written in Markdown and use Pandoc to produce a beautiful, professional-looking document. I’ll begin by running the most basic pandoc command and we’ll review the output to see how well it meets the requirements. From there, I’ll gradually enhance the process by adding optional parameters and a few auxiliary files. Each step will introduce small changes, allowing us to see the evolving output. By the end, you’ll have a good sense of what's possible and where to look if you need additional features.

Disclaimer

Before we dive in, there are a few things I want to mention—not to discourage you, but to set the stage:

  • I use a Linux machine to write Docs, and my system is already set up with all the tools I need. Your setup might differ, but don’t worry — it’s easier than it might seem. You only need three key components:

    1. A text editor: Any one is fine (Neovim, Wordpad, Notepad++, TextEdit, or whatever you prefer). Most systems already have one installed.
    2. A pandoc and LaTeX installation, or alternatively, a Docker image that I’ve created and published on Docker Hub.
    3. If you choose the Docker route (which I recommend), you’ll also need a running Docker Engine.

I’ve written a System Setup page to guide you. While it doesn’t cover the actual installation of pandoc, LaTeX, or Docker, it links to detailed guides that explain it better than I could.

  • You’ll need to use the command line to generate the PDF output. This might seem intimidating at first, but once you get comfortable, you’ll discover just how powerful the command line can be.

  • Setting up your system and working through this tutorial might take a bit of time, and you may wonder if this is really a faster way to create Docs. Trust me — it is. The setup only needs to be done once, and while learning something new always takes a little effort, the payoff is huge in the long run. Once you’ve mastered the basics, the Docs as Code approach will save you a lot of time.

Let's start by looking on the benefits of the DaC approach.