Start with the problem, not Git
Docs-as-Code is often presented as a tool stack: Markdown, Git, pull requests, CI, and a static-site generator. That leads teams to argue about editors and branch strategy before asking the useful question: what is actually broken in the documentation workflow?
Maybe nobody knows which procedure is current. Product changes ship before docs. An SME receives forty pages to review instead of three changed lines. Terminology drifts. Broken links are discovered by customers. Publishing depends on one person and one laptop.
Docs-as-Code is valuable when it makes these problems measurably easier. If writing becomes harder, review becomes harder, and publishing is still manual, the team has only exchanged one form of friction for another.
What Docs-as-Code actually contains
Git is only one layer. Think about the path from a product change to a published page.
| Stage | What happens | Simple implementation | More mature implementation |
|---|---|---|---|
| Source | Author changes content | Markdown/AsciiDoc in Git | Structured content plus metadata schema |
| Editing | Author works with the source | GitHub file editor | github.dev, VS Code, IDE, or authoring UI |
| Preview | Author sees the future page | local/web build | preview for every branch/change |
| Automated checks | machines catch routine defects | links + build | style, terms, schema, accessibility, API examples, locales |
| Review | humans verify meaning | one reviewer | SME review plus editorial review |
| Merge | change becomes canonical | commit to main | protected branch, checks, approval |
| Publish | site is updated | manual build | CI/CD after successful checks |
| Post-release | published output is checked | manual sampling | link checks, smoke tests, monitoring |
The goal is not maximum complexity in every row. Choose the minimum sufficient level for each stage.
A text format does not require an IDE
“Store docs in Git” is too often translated into “everyone must use VS Code and the terminal.” That is not true.
GitHub has a normal browser file editor. An occasional contributor can open a Markdown file, edit it, and commit the change. For longer work, github.dev runs in the browser and adds repository search, syntax highlighting, and source-control views without requiring a local clone. It can be opened from a repository or with the . shortcut.
| Contributor | Usually sufficient | Do not require without a reason |
|---|---|---|
| Daily technical writer | github.dev, VS Code, or preferred editor |
a specific IDE because developers use it |
| SME once a month | GitHub web editor + preview | terminal, rebase, local build |
| Developer | IDE + Git | separate CMS if Markdown beside code is easier |
| Editor | browser editor or authoring UI | knowledge of pipeline internals |
| Translator | web/localization layer | manual branch management for every line |
Good Docs-as-Code separates storage format from authoring interface. The canonical source can remain versioned text while each participant gets the simplest interface that fits the job.
A practical end-to-end workflow
A common product-documentation path is:
Product change → draft → preview → automated checks → technical review → editorial review → merge → publish → production check.
A small team may combine roles. That is fine. Do not create a pull request as a ritual when the author and publisher are the same person and the risk is low. Automated builds and checks can still protect the main branch.
In larger teams, separate responsibilities. The SME verifies facts. The technical writer verifies the user task, information structure, terminology, and clarity. The machine verifies things that can be expressed as deterministic rules.
Which checks are worth automating
Automation works best when the question can be reduced to yes/no or compared with a formal rule.
| Check | What it catches | When to run | A useful failure should show |
|---|---|---|---|
| Build | broken syntax, includes, templates | every change | file and concrete cause |
| Internal links | removed pages, wrong anchors | every change | source and target |
| External links | 404/410, redirect loops | scheduled | URL and status; do not fail releases on random timeout |
| Metadata | missing title, owner, locale, revision | every change | missing/invalid field |
| Heading structure | missing/incorrect hierarchy | every change | exact heading that violates the rule |
| Terminology | banned or obsolete terms | every change | term and preferred replacement |
| Style lint | selected editorial patterns | every change | short actionable explanation |
| Code examples | syntax, format, sometimes execution | every change | failing example and reason |
| API contract | examples drifting from OpenAPI/schema | API-doc changes | field/endpoint mismatch |
| Images | missing asset, alt text, oversized file | every change | asset and violation |
| Accessibility | formal HTML/Markdown patterns | build/preview | element that needs attention |
| Locales | missing required language/revision drift | every change | article and locale that lag |
| Secrets/PII | token, key, password, personal data | every change | finding type without leaking the secret into logs |
| Duplicate prose | repeated large blocks | change/scheduled | both affected pages |
A warning that nobody intends to fix should be improved or removed. Hundreds of warnings do not prove maturity; they train the team to ignore automation.
How much time can automation save?
There is no honest universal claim that “Docs-as-Code saves 37%.” Teams start with different workflows. Industrial code-review research does show that automating repetitive review work can remove meaningful manual effort, but applying a software-engineering percentage directly to documentation would be misleading.
Use a transparent local model instead. Suppose a team ships 40 documentation changes per month. Manual checks for links, metadata, terminology, build, and basic structure take 20 active minutes per change: 800 minutes, or 13 hours 20 minutes. After automating them, the author spends about 2 active minutes inspecting results and fixing failures: about 1 hour 20 minutes. Under those assumptions, roughly 12 active hours per month are freed from that specific routine.
Assumption: 40 changes × 20 minutes of manual routine versus 40 × 2 minutes inspecting automation results. This is a planning model, not an industry benchmark.
The assumptions matter more than the graphic. Five changes per month yield a different result. A noisy link checker with many false alarms can even increase total time.
Measure your own effect instead of inventing a study
TechWriters should not claim that “we studied several projects and proved the savings” until we have actually run such a study. A credible internal experiment is straightforward.
Across two to five projects for four weeks, record:
- active authoring time before review;
- review waiting time;
- active SME and editor review time;
- comments that could have been caught mechanically;
- defects discovered after publication;
- time from ready content to production;
- false positives produced by automated checks.
Then automate one class of defects — for example links, metadata, and builds — and repeat the measurement. That produces a real TechWriters case study with context, volume, trade-offs, and failure modes instead of a decorative percentage.
Humans and machines should review different things
A bad pipeline tries to automate everything. A good one removes routine work so human attention is spent on judgment.
| Machines are good at | Humans must judge |
|---|---|
| whether a link exists | whether it is the right destination for the user |
| whether a required heading exists | whether the information is structured around the task |
| whether a term is allowed | whether the term is clear for this audience |
| whether an example matches a schema | whether the example teaches a real task |
whether updated is populated |
whether the page is actually current |
| whether the page builds | whether the page helps someone succeed |
This becomes even more important with LLM checks. AI can flag contradictions, propose edits, and identify suspicious claims, but facts still need confirmation from the product, specification, test, or responsible expert rather than the model’s confidence.
Where fanaticism begins
Fanaticism does not begin with Git. It begins when process purity matters more than the result and the participants.
If an SME can correct a parameter name in a browser in two minutes, do not require Node.js, a local clone, a branch, and conflict resolution. If a writer prefers VS Code, do not force a simplified form. If review is necessary, keep it. If a typo in a small team is safe behind automated checks and a direct commit, do not create ceremony just to look like a development team.
Provide an escape hatch: browser editing, an issue template, assisted authoring, or a person who accepts the change and carries it through Git. The canonical process stays controlled without requiring everyone to enter it in the same way.
Roll out Docs-as-Code in stages
Start with one repository and one documentation type.
- Week 1: put sources in Git and make the history understandable.
- Week 2: add preview and automated build.
- Week 3: enable three to five useful checks: broken links, metadata, terminology, build, required locales.
- Week 4: separate technical and editorial review where the risk justifies it.
- After one month: measure lead time, manual routine, defects, and noisy warnings before adding more automation.
Docs-as-Code works when authors can change content more easily, experts can verify facts faster, editors can see meaningful issues, and users receive current information sooner — not when the README contains the most sophisticated diagram.
