# Example: a basic docs-as-code workflow

> **Note: Worked example**
>
> This is a **finished illustration to study**, not a template. For the checklist version, see [docs-as-code adoption](https://docs.redaction-technique.org/en/toolkit/docs-as-code-adoption-checklist/).

## The scenario

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

## The workflow

```mermaid
%%{init: {"flowchart": {"curve": "basis"}, "themeVariables": {"fontFamily": "IBM Plex Sans Variable, sans-serif"}}}%%
flowchart TD
    accTitle: Basic Docs-as-Code Workflow
    accDescr: Sequential progression of a documentation change from branch creation to production deployment.

    A["1. Branch<br/>(Single-purpose topic branch)"] --> B["2. Edit and commit<br/>(Structured content & explicit messages)"]
    B --> C["3. Push and open PR<br/>(Context & issue linking)"]
    C --> D["4. Automated CI<br/>(Build, link check & preview deploy)"]
    D --> E["5. Technical & peer review<br/>(Accuracy check against checklist)"]
    E --> F["6. Merge to main<br/>(Approval & green CI gates)"]
    F --> G["7. Automated deployment<br/>(Production publish via pipeline)"]

    classDef stage fill:#f1f5f9,stroke:#64748b,stroke-width:1.5px,color:#0f172a,font-weight:500
    classDef gate fill:#e2e8f0,stroke:#3b82f6,stroke-width:1.5px,color:#1e293b,font-weight:600

    class A,B,C,F stage
    class D,E,G gate

    linkStyle default stroke:#64748b,stroke-width:1.5px
```

1. **Branch.**

   ```bash
   git checkout -b docs/add-firewall-port
   ```

   See [using branches](https://docs.redaction-technique.org/en/tech-writing-process/using-branches/) — a small, single-purpose branch like this one is exactly what branching is for.

2. **Edit and commit.**

   ```bash
   # 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 request.**

   ```bash
   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](https://docs.redaction-technique.org/en/tech-writing-process/integrating-documentation-into-development/).

5. **Review.** A teammate with access to the actual firewall configuration confirms the port number against [the technical review checklist](https://docs.redaction-technique.org/en/toolkit/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

- 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.

---

Source: https://docs.redaction-technique.org/en/toolkit/example-docs-as-code-workflow/