Services / CI/CD

Docs-as-Code CI/CD Publishing Pipelines

With docs-as-code, your documentation lives in Git alongside your product, and a CI/CD pipeline builds it automatically. Writers and engineers update docs through the same merges and pull requests they already use, and the published site stays current without anyone having to remember to rebuild it.

Common documentation publishing issues

  • Publishing depends on one person running a build by hand, so docs fall behind each release.
  • Docs live in a separate CMS or wiki from the code, so engineers don't update them when features change.
  • There is no review step, so mistakes go straight to customers.
  • Docs for older releases are overwritten, and customers on those versions lose their documentation.

The Process

  • I audit your current documentation setup: where the source lives, how it is built, where it is published, and who updates it.
  • I choose the right site generator for your needs, usually Antora or Docusaurus, and set up the build in your repository.
  • I write the pipeline on your existing Git platform, so the site rebuilds automatically when changes are merged.
  • I set up a preview branch, so changes are built and reviewed on a preview site before they are merged to the main branch and go live.
  • Where you need it, I set up versioned documentation, so each release keeps its own docs. I worked with this in Antora at GraphAware, where each version had its own branch.
  • I connect the build to your hosting. For static hosting I can write the deployment step myself, or I can hand over a finished build for your web team to deploy.
  • I hand over the pipeline with documentation on how it works, so your team can maintain it after I leave.

The Advantages

  • Merge or pull requests update the documentation automatically.
  • Staging and review are built into the process, with a preview site in the pipeline.
  • The site is easily personalised through stylesheets and UI updates.
  • Different pipelines can build different release versions and patches.

Example: moving Kaptio from a CMS to an Antora pipeline

At Kaptio, the documentation was managed in a basic CMS and had fallen out of date. I moved it to docs-as-code with Antora and built the CI pipeline that generated the site.

The pipeline built the docs on every merge to a develop branch, so changes could be reviewed on a preview site, and then again on merge to the product branch for the live site. I first set this up in Bitbucket Pipelines, and when the company moved to GitLab, I rebuilt the same process in GitLab CI/CD. The company's System Architect handled the final deployment step with Terraform.

The result was a fast, easily navigated static documentation site, updated through the same Git workflow the engineers already used, with no manual publishing step.

PDF output: Tern Systems

Not every team needs a website. At Tern Systems, I set up an AsciiDoc-to-PDF build process using Asciidoctor PDF for air traffic control software documentation, and handed it to the DevOps team to run. Docs-as-code can produce print-ready manuals as well as websites.

Platforms

I have built documentation pipelines in Bitbucket Pipelines and GitLab CI/CD, and have used GitHub Actions on my own projects. Whichever Git platform you use, the pipeline fits into your existing system rather than replacing it.

Related: Antora and Docusaurus sites · API reference sites

Want to discuss a pipeline? Email me

Email All services