Don't Panic: Documentation CI and Automated Publishing

Documentation does not become reliable because somebody put Markdown in Git. The useful change is a documentation pipeline: source files enter, checked pages come out, and only approved pages reach the site. The source is what people edit. The rendered site is the output, much as a compiled program is output from code. Editing that output by hand is a good way to have your work disappear at the next build.

There are two journeys through this pipeline. A proposed change travels through validation. A runner checks the source, builds the pages, and reports what happened. A reviewer can inspect a rendered preview and decide whether the words and examples are correct. The approved change travels through publishing. A job delivers the built pages to a host. These journeys may use the same repository, but they have different permissions. A draft should not need the credentials that can replace the live site.

A green check is reassuring in exactly the way a completed checklist is reassuring: it tells you what was checked. A strict build can complain about a missing navigation target. A prose linter can find a word that breaks a style rule. A link checker can detect an unreachable destination. None of them can tell you that the destination explains the right concept or that the example command actually solves the reader's problem. That is where a human review earns its chair.

The output also has a history. A build artifact is the rendered site produced from a source revision, configuration, and tool versions. If the publishing job uses different tool versions from the validation job, the public pages may differ from the pages reviewers saw. Record those inputs or carry the tested artifact into deployment. Then record which source revision the host serves. A successful deploy log is less comforting when the live URL still shows yesterday's navigation.

Several services can handle parts of the journey. A generator such as MkDocs or Docusaurus creates the static pages. GitHub Pages or GitLab Pages can serve them from repository automation. Read the Docs can manage the build and upload from a connected repository. Netlify can expose a pull request preview. The arrangement matters less than knowing which stage checks, which stage publishes, and who can trigger each one.

If the pipeline fails, locate the stage first. No run suggests a trigger problem. A failed build suggests source, configuration, or dependency trouble. A good build with a bad preview points toward rendering or path settings. A good deploy with stale pages points toward the publishing target or host. The Cheatsheet maps those signals; the Practice Reference helps define a release contract. Use the Exercise to watch a strict build reject a broken page before a publishing job ever enters the picture.