Skip to content
Olivier CarrèreTechnical writing practice

Example: a basic docs-as-code workflow

Task
Docs-as-codeCI/CDDocumentation review

A worked example of a single documentation change moving from branch to merge under a docs-as-code workflow, mirroring a standard code review flow.

, 1 min read

View as Markdown

The scenario

Section titled “The scenario”

A support ticket reveals that the installation guide is missing a required firewall port. One writer fixes it.

The workflow

Section titled “The workflow”
Basic Docs-as-Code WorkflowSequential progression of a documentation change from branch creation to production deployment.1. Branch(Single-purpose topicbranch)2. Edit and commit(Structured content &explicit messages)3. Push and open PR(Context & issuelinking)4. Automated CI(Build, link check &preview deploy)5. Technical & peerreview(Accuracy check againstchecklist)6. Merge to main(Approval & green CIgates)7. Automated deployment(Production publish viapipeline)

  1. BranchA parallel line of work in a version-control system: changes made on a branch stay isolated until they are reviewed and merged back into the main line, so several writers, releases or languages can progress at the same time.View in glossary →.

    Terminal window
    git checkout -b docs/add-firewall-port

    See using branches - a small, single-purpose branch like this one is exactly what branching is for.

  2. Edit and CommitA recorded snapshot of changes in a Git repository, with an author, a date, and a message explaining the change. Commits form the project history that branches start from and that reviewers and translators compare.View in glossary →.

    Terminal window
    # edit installation.md
    git add installation.md
    git commit -m "docs: add required firewall port 8443 to installation guide"

    The commit message states what changed and, implicitly, why - a future reader of git blame shouldn’t have to guess.

  3. Push and open a Pull requestA request to merge a branch's changes into the main line, presented as a reviewable set of differences: reviewers comment, automated checks run, and approval is recorded before publication. GitLab calls it a merge request.View in glossary →.

    Terminal window
    git push -u origin docs/add-firewall-port

    The PR description links the support ticket that prompted the fix.

  4. CI runs automatically. The build compiles the site from this branch, a link checker runs against the output, and a preview deployment is generated - see integrating documentation into development, and the CI/CD pipeline example for the stages in detail.

  5. Review. A teammate with access to the actual firewall configuration confirms the port number against the technical review checklist - not against their memory of what it “should” be.

  6. Merge. Once CI passes and review approves, the branch merges to main.

  7. Deploy. The same pipeline that built the preview now builds and publishes the production site - no separate manual publish step.

Why this works

Section titled “Why this works”
  • Every step that can be automated (build, link check, preview, deploy) is - a human only does the parts that need judgment: writing the fix and reviewing its accuracy.
  • The PR is the single place where the change, its justification, its CI results, and its review conversation all live together - useful history for anyone who asks “why does the guide say port 8443?” a year from now.
  • Nothing shipped without CI passing - the same guarantee code changes get.