Consent

This site uses third party services that need your consent. Learn more

Skip to content

Blog

What is "docs like code"?

Headshot of Craig.

Craig Wright

“Docs like code” is an approach to technical communication that uses the same tools and workflows that developers use when creating software. It involves storing and managing content in a version control system, typically Git, and using tools to build and publish it automatically.

Note: The term “docs like code” is widely used in the technical communication community. It most likely originated in the book of the same name by Anne Gentle. You might also hear this approach called “Docs as code”.

Icons showing the typical docs-like-code workflow. It starts with creating markdown content in files. Those are uploaded to GitHub. A static site generator converts them into HTML. Automation publishes the HTML to a site.
Docs like code is an approach that uses a combination of tools to produce a documentation website.

Working in the same tools as developers?

When I first heard that docs like code has writers using developer tools, I had instant reservations. I had a few concerns and spent some time getting answers before proceeding. Here’s what I found out:

  • Am I going to have to learn to write code?
    No, not unless you need to know it for writing your docs. Some developer know-how is useful for setting things up and customising later on though. The things you will definitely need to know are: how to use version control, how to write in a lightweight format, and it’d be a good idea to understand the entire process from new docs request to publishing.

  • Is docs like code just for developer documentation like APIs?
    No, although it is often used for those as well as regular user docs for software. Creating print manuals with complex layouts can be more challenging though, so that’s something to bear in mind.

  • What about the “tech comm” features I expect, like content reuse?
    Don’t worry, most of those are available, but it will vary depending on which static site generator you use to build your site (more on that later). Some support these more advanced features, but not all of them do.

  • What about the actual writing? Where do I do that?
    You’ll most likely write in Markdown (a lightweight format) and you create Markdown files in pretty much any text editor.

At the time of writing, I’ve spent most of my career working in dedicated technical writing products, like FrameMaker, MadCap Flare and Paligo, as well as help centres such as Zendesk and Intercom. So working in Markdown in a basic editor feels like a backwards step. But let’s see how it pans out as we learn more. I know technical writers who much prefer docs like code, so maybe they are on to something?

Benefits of docs like code

Before we start looking at the basics, let’s take a look at the benefits of docs like code. I don’t know about you, but I need that promise of a different or better way to keep my motivation going.

From asking around, it seems the main benefits of docs like code are:

  • Developers already understand the tools and workflows, so it is easier for them to contribute and review.

  • It helps to keep the documentation and code aligned. Documentation can be made part of the workflow, so that its easier for developers to notify technical writers of changes.

  • Automation means there’s less manual work required to build, test, and publish documentation.

  • Version control means writers can:

    • Keep track of changes, including what changes were made, who made them, and why

    • Revert back to earlier versions if required

    • Create new versions based on existing versions

    • Work on the same content files as other writers and developers, at the same time.

  • No vendor tie-in*.
    Docs like code is an approach rather than a system or a product. It uses open source tools and widely used formats and standards. You can switch tools over time as your needs change, without the massive overhead of migrating and converting content.

    * It is possible to have some vendor tie-in, but that’s dependent on the tools you choose.

  • Lower licensing cost
    Some of the docs like code software is free or low cost, so the price-per-user is much less than with technical writing tools. Also, as you’re using the same tools as developers, there may already be licences paid-for and available.

There are some downsides too, which I’ll cover in a later post.

How is it different to using a dedicated technical writing tool?

With a dedicated technical writing tool or knowledge base tool, everything you need is right there in one product. You create, style, review, and publish using the same tool. Of course, the problem with that is that developers are unlikely to know that tool, so it can make reviewing and contributing more complicated for them. Your docs files are also going to live outside their working environment, making it harder to integrate docs into their workflows.

With docs like code, you’ll use a combination of tools to create, manage, publish and style your documentation.

What do you need for docs like code?

To use a docs like code workflow, you need several components:

  • Version control system

  • Text editor that’s suitable for your markup language

  • Linting and style checkers

  • Static Site Generator (SSG)

  • Hosting

Version control system

There are different version control systems available, but the one you’ll likely hear mentioned the most is Git. And there are some other tools with Git in the name that can confuse things, so let’s quickly go over them here:

  • Git is the engine for version control. It tracks changes in your files and you run it locally on your computer. It is usually pre-installed on Macs but you’ll need to install it manually on Windows.

  • GitHub is a cloud-based platform for hosting Git repositories. Repositories are often shortened to “repos” and they are just like a folder but with version control features built-in. You will use GitHub to store your content online, manage your content, collaborate with other contributors, and build, test, and publish your site to a host.

  • GitHub Actions is a tool that’s included with GitHub and it handles the automated tasks.

  • GitHub Pages is a hosting service that’s included with GitHub. You can use it to publish your documentation site.

  • GitLab is a GitHub alternative, mainly aimed at enterprises as it has additional features and offers more flexible hosting options.

Text editor that’s suitable for your markup language

You can use any text editor that supports the type of markup language you are going to use. The most common markup language is Markdown, but it’s also possible to use reStructuredText or Asciidoc.

For those of you who prefer a visual UI, there are also CMSs that support Markdown editing, such as Netlify CMS and TinaCMS. These are often easier for non-technical contributors. I’ve not tried a CMS with docs like code yet, but I plan to do that in the future.

For learning Markdown and Git, I used Visual Studio Code which is a free Microsoft product. It has Markdown extensions and shows HTML previews of your work, which is nice. It also has some UI features for managing the version control parts, which I find easier to use than writing commands in the terminal (you’ll see what I mean in later posts about Git and GitHub).

Markdown content in Visual Studio Code. There are three columns, the left is navigation, the middle is the editor where the content is entered in Markdown and the right column is an HTML preview.
Markdown content in Visual Studio Code

Linting and style checks

Prior to looking at docs like code, I had never even heard the term linting. It means checking your content against a defined set of rules. There are various linting tools available, such as Vale and Markdownlint. You can download them and run them locally while you are writing. You can also set up GitHub Actions to run them automatically when you (or your colleagues) “push” content from your local machine to GitHub.

Note: If you use Visual Studio Code for editing, it has extensions for various linting tools, including Vale, Markdownlint, and spell checkers.

Linter used to highlight problems with markdown content in Visual Studio Code. There is a yellow underline to indicate where the problem is and a hover pop-up with information about the issue.
Markdownlint in action. It underlines errors and has a pop-up to explain. You can correct manually or use Copilot AI.

Static Site Generator (SSG)

You’ll need a Static Site Generator (SSG) to turn your plain text content into a finished, styled HTML website. Some of the most popular ones are MKDocs, Docusaurus, Hugo, and Jekyll.

When choosing an SSG, make sure it supports the markup language you are using (Markdown, ReStructuredText, Asciidoc, etc.) and the features you need. For example, some SSGs do not support content reuse, so be mindful of that. You’ll find that there are more options for Markdown than other markup languages, as it is the most popular. (Even though other languages are arguably better for technical communication purposes).

Hosting

Once the documentation has been built using the Static Site Generator, you need to host it somewhere to make it available online. GitHubPages is a popular free hosting service, but there are others you can use, such as Netlify.

Summary

Okay, that’s the basics of how all the different components come together to create the documentation workflow, experience, and output. It can be a bit daunting at first, but if you think about it, some of the technical writing tools like Flare and Paligo do similar things as this combination of products, so it isn’t quite as big a leap as it might seem at first.

In my next post, I’ll start looking at setting up GitHub and connecting it to Visual Code Studio.

Useful resources

Posted under Docs like code

Last modified: 3 August 2025

Headshot of Craig.

Craig Wright is an experienced technical writer based in Chesterfield, UK.  He hates writing about himself in the third person, so I shall stop now.

Always interested in new content writing opportunities. Remote working preferred.

Contact Craig

Get in touch

Let’s talk about your project

I’m here to help and offer my expertise as a technical writer. Get in touch and let me know what you need.
Contact Straygoat Learn more