Introduction to docs-as-code: A guide to managing documentation with a developer workflow

README.md

getting-started.md

tutorial/

calling-the-api.md

creating-an-account.md

# Calling the API

In order to call the API, you have to first acquire an API key.
This can be done in the product dashboard, after you have created your account.
[API reference](/docs/api/).
    

What is docs-as-code?

Docs-as-code refers to the process of managing your documentation like your source code: using plain text formats, collaborating with a Git-based workflow, and deploying your documentation automatically from CI/CD.

This is in contrast to using for example cloud-based CMS tools, where the source of truth for your documentation is separate from your code. And while XML-based tools like DITA or Docbook can be managed in a Git repository, it's more common to use plain-text formats like Markdown, AsciiDoc, or reStructuredText which can be manipulated easily in a text editor.

Since the documentation's source of truth is your Git repository, collaboration happens through pull-requests, and changes are deployed automatically from a CI/CD pipeline.

The docs-as-code workflow

Docs-as-code means using a software engineering workflow for your documentation. It typically has the following stages:

Everything starts with having your documentation in source control. Using formats like Markdown lets you easily update your documentation locally using your text editor of choice. Once you are happy with your changes, you create a new branch in Git, and commit your changes.

Next step is review. Since we are following a software-engineering workflow, this most likely means using pull-requests on a platform like GitHub. This is where your colleagues can leave feedback and ultimately OK your changes.

It's common to create isolated preview environments of your documentation as part of the review process, so your reviewers can see your changes in the context of the final rendered documentation.

Another great benefit of docs-as-code is being able to run automated checks during the build process. You can run broken link checkers, prose linters, and other checks when you make changes. The natural place to do this is part of a CI/CD pipeline, which gets executed for each pull-request.

Finally, it's time to publish your changes! Depending on how your product is released, you may be doing continuous documentation where your latest documentation goes live immediately. In this case, after the changes are merged, another CI/CD pipeline is executed to deploy the documentation to production. Alternatively, it may only be merged into a release branch in preparation for a scheduled release.

What are the benefits of docs-as-code?

Let's look at some of the benefits of co-locating your documentation with your source code.

Technical writers and developers can use a common workflow

A common problem teams have is that developers especially do not want to contribute to documentation. One way to combat this, is to lower the barrier to contributing to documentation. And for developers, this means bringing your docs near your source code.

Companies like Google, Spotify, and Twitter found that co-locating source code and documentation was an important driver in creating a culture of documentation in their organisations among engineers.

Another option is using a cloud-based documentation platform. But this means contributors have to learn another tool, and coordinate releases between two different systems. This is not a problem when Git is the source of truth for your content.

It fits well into teams with a strong engineering culture

It's common for engineering teams to want to do "everything-as-code". Infrastructure-as-code became popular because teams realised it's better to have the source of truth for your infrastructure be as close to the source code as possible: infrastructure changes could be managed just like code changes.

Doc-as-code is the same principle applied to documentation. Keep your documentation and the code it is describing as close to each other as possible.

The vast majority of engineering teams are already using Git-based collaboration workflows fluently. Why not use the same process for your documentation as well?

Documentation versioning happens naturally

Versioning your documentation with docs-as-code is delightfully straightforward: you use Git branches, just like with code.

You can take your product's versioning strategy, and use it for documentation as well. In fact, in monorepo environments where your documentation lives in the same repository as your code, there is nothing else to do to version your docs: it automatically matches your product's version. Just make sure your tools support these workflows!

Auto-generating documentation

Not all documentation is Markdown and written by humans. Some documentation is generated from source code or specifications like OpenAPI. Auto-generating documentation from source code works great in a docs-as-code setting.

Since your documentation is already near your source code, it's straightforward to generate documentation artefacts either as part of CI/CD, or with a script that gets executed on demand. Especially compared to manually copy-pasting possibly hundreds of pieces of auto-generated content into a cloud-based CMS.

Common objections

Docs-as-code is not a magic bullet that solves all your documentation problems. So what are some common objections or down sides?

"It's requires a lot of devops/docops"

Compared to cloud-based documentation platforms, docs-as-code can be more complicated to implement technically. You will have to choose a framework, such as a static site generator like Docusaurus. You will also have to think about where to host your documentation, and set up your CI/CD pipeline for publishing and reviewing documentation changes. Finally, you have to integrate your documentation with a search provider like Algolia, as well as any analytics systems you may need.

Managed docs-as-code platforms like Doctave will make a lot of this easier. They take care of a lot of the technical setup, and let you focus on your content instead of your infrastructure.

But once you have set up your docs-as-code publishing pipeline, you'll be able to use a pull-request based workflow, which is something cloud-based CMS services won't be able to handle (well). If an engineering workflow is important for your team, the setup complexity is a price worth paying.

"You can't reuse content"

This is an objection you commonly hear from DITA/DocBook advocates, where topic-based authoring is the norm. They are right that Markdown does not have native support for reusing content. This is why it's common to pair Markdown with a templating engine such as Liquid. This will allow you to extract commonly used content into partials that can be included across your docs. Tom Johnson over at I'd Rather Be Writing has written an article comparing content reuse in DITA vs Jekyll.

"There's too much friction to making changes"

This is a matter of opinion. Some say that documentation should be easy to edit, and the review process should not be as involved as e.g. code changes.

Docs-as-code advocates would argue that the "friction" of using a Git-based pull-request workflow for changes is a benefit. Changes will be more deliberate and you can track down the history of any change you've made. It's also easy to go back in time, or branch off new versions when you like.

If you want to be able to make edits quickly and without a review process, docs-as-code may not be a good choice.

Want to read more? Here are some other resources:

• Docs-as-code versioning best practices
• Should you use docs-as-code?
• Docs-as-code at I'd Rather Be Writing