Skip to content

content: Where the Docs-as-Code Workflow Stops #796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
frances720 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

content: Where the Docs-as-Code Workflow Stops #796

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions src/content/blog/technical/where-the-docs-as-code-workflow-stops.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
---
title: 'Where the Docs-as-Code Workflow Stops'
subtitle: Published July 2026
description: >-
Docs-as-code solves the tooling problem for documentation. It can't tell you which docs break when code changes. Here's the gap and how to close it.
date: '2026-07-28T00:00:00.000Z'
author: Frances
tag: Technical
section: Use Cases
hidden: false
---
import BlogNewsletterCTA from '@components/site/BlogNewsletterCTA.astro';
import BlogRequestDemo from '@components/site/BlogRequestDemo.astro';

Your team has been on docs-as-code for 18 months. Markdown files, Git repository, pull request workflow, CI pipeline that deploys on every merge to main. You followed the playbook.

At a developer conference last month, three attendees separately asked about an authentication method your product dropped in version 3.2. They had all read it in your quickstart. The quickstart was in your repository, right next to the code that made it wrong.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — the hook collides two points of view, so the reader cannot tell whose story this is

"At a developer conference last month" is a first-person anecdote: someone was there and observed this. "your product," "your quickstart," and "version 3.2" make it the reader's product. The two cannot both be true. The reader stalls trying to decide whether this is a real event Promptless witnessed or a hypothetical addressed to them. The style guide asks for a hook grounded in a concrete situation; the fix is to commit to one frame.

Also: "They had all read it in your quickstart" — "it" points back to "an authentication method." You don't read a method, you read about one.

Suggested fix (commits to the hypothetical, keeps the specificity):

Three developers file the same support ticket in one week. They are all calling an
authentication endpoint your product dropped in version 3.2. They all got it from
your quickstart, which sits in your repository, one directory away from the code
that made it wrong.


Docs-as-code gets documentation into the right tooling. That turns out to be the easier half of the problem.

## What docs-as-code actually solves

Docs-as-code is a set of conventions borrowed from software engineering: documentation lives in source control alongside the code, and changes go through pull requests with CI/CD deployment.

These conventions solve real problems. Writers can submit pull requests that bundle a code change and its documentation update in the same diff. Reviewers see both together. CI can run link checks and linting before anything merges. Documentation gets the same version history as the code, with rollback capabilities.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion — hidden verb

"with rollback capabilities" → "and you can roll changes back."


Before docs-as-code, documentation often lived in a separate wiki or help center, edited by whoever had access, with no useful history of what changed or why. Moving documentation into Git removes an entire class of organizational problems.

But docs-as-code doesn't specify what happens between a code change and a documentation update. It assumes someone updates the docs when code changes. The mechanism for that is discipline.

## Why discipline doesn't scale

When an engineer merges a PR that deprecates an endpoint, they know the docs need updating. They're also immediately pulled into the next ticket. The update gets filed as "I'll get to it." The docs stay wrong.

Teams add a documentation section to PR templates. Engineers check the box. Sometimes the doc gets updated; often it doesn't. The template creates the appearance of process without the substance.

A dedicated documentation owner helps, but it shifts the problem rather than solving it. Now the writer has to discover that a change happened. They watch Slack and scan pull request descriptions, hoping to catch changes before they surface as support tickets. This is surveillance work, and it doesn't scale as the codebase grows.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion — same concept named different ways, and one verb overstates

This paragraph shifts from "a dedicated documentation owner" to "the writer" mid-paragraph. Pick one term and use it consistently.

Also: "A dedicated documentation owner helps, but it shifts the problem rather than solving it." If it only shifts the problem, "helps" overstates it. Consider: "A dedicated documentation owner moves the problem rather than solving it."


According to a Postman survey, 68% of developers cite outdated documentation as their top frustration with APIs. Most of those companies have a docs-as-code workflow.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Critical — unsupported claim inherits the authority of the statistic next to it

The second sentence is the load-bearing claim of the entire article: it is what makes an API-frustration statistic relevant to a docs-as-code audience. Placed immediately after "According to a Postman survey," it reads as a survey finding. The Postman State of the API report does not measure docs-as-code adoption, Git-based docs workflows, or documentation tooling at surveyed companies at all. A reader who checks the source finds the 68% and no basis for "most of those companies."

This is an understand failure: the reader forms a belief about what the evidence supports that the evidence does not support. It is also a find failure — "According to a Postman survey" gives the reader no way to locate the source. Six other articles in this repo cite the same figure with a linked, year-qualified attribution (for example api-changelog-best-practices.mdx:19, interactive-api-documentation.mdx:31).

Suggested fix — cite properly and drop or ground the second sentence:

The [Postman 2024 State of the API report](https://www.postman.com/state-of-api/2024),
which surveyed over 5,600 developers, found that 68% of developers cite outdated
documentation as their top frustration when working with APIs.

If the docs-as-code framing is essential, it needs its own evidence, or state it as the observation it is: "Outdated docs are not a symptom of missing tooling. Teams with mature docs-as-code workflows report the same frustration."


<BlogNewsletterCTA />

## The synchronization problem

Version control tracks that documentation changed. It cannot detect which documentation should change in response to a code modification.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion — inconsistent terminology

"a code modification" — the article says "a code change" everywhere else (:29, :65). Use "code change" here too.


The two systems operate independently. There is no connection in the data model that links `src/auth/token.py` to `docs/authentication/getting-started.md`. Git knows both files exist and tracks their individual histories. A change to the first one doesn't register as relevant to the second.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — ambiguous antecedent and vague expletive open the key explanatory paragraph

"The two systems" has no clear referent: the preceding sentence names only version control. The reader has to guess (code and docs? Git and the docs site? the repo and the pipeline?). "the data model" is equally unanchored — whose data model? This is the paragraph that carries the article's central mechanism, so vagueness here costs the most.

Suggested fix:

Git tracks files, not the relationships between them. Nothing in its data model links
`src/auth/token.py` to `docs/authentication/getting-started.md`. Git knows both files
exist and tracks their histories separately. A change to the first does not register
as relevant to the second.


This is what docs-as-code leaves open. Proximity is solved: docs live next to code, versioned and reviewable. Synchronization remains manual: nothing tells you which docs broke when a PR merged.

The result is a false sense of hygiene. The docs are in Git, so they feel maintained. That they're wrong isn't visible until a developer files a support ticket or an API integration fails.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — abstraction carrying weight it cannot hold

"The result is a false sense of hygiene" — "hygiene" is vague as a noun here. And "That they're wrong isn't visible until a developer files a support ticket" front-loads a subordinate clause and buries the actor in a negative construction.

Suggested fix:

The docs are in Git, so they look maintained. Nobody finds out they are wrong
until a developer files a support ticket or an integration breaks.


## Why this matters more now

[Documentation drift](/blog/technical/documentation-drift-detection-problem) has always been a problem. The cost increased when AI coding assistants became a primary way developers interact with APIs.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion — cost of what, to whom?

"The cost increased when…" leaves the noun unattached. → "The cost of drift increased when…"


AI agents read your documentation and act on it. Unlike a developer, an agent doesn't get skeptical when something feels dated. It takes your docs at face value and generates code accordingly. The State of Docs Report 2026 found that technical writers are already responding to this shift: spending less time drafting and more time fact-checking and validating. The role has moved toward verification.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Critical — statistic attributed to a report that does not contain it, and not linked

Three problems stacked:

  • Attribution. The 2026 report's AI section reports 78% saying AI makes documentation faster, and finds technical writers see the smallest gains (31% at 50%+ savings). It contains no finding that writers spend less time drafting and more time fact-checking; the words "fact-checking" do not appear. The nearest material is a qualitative practitioner quote about acting as "editors and reviewers," not a measured time shift among technical writers.
  • No link. documentation-debt.mdx:27 links the 2025 edition inline. This one does not, so the reader cannot check it.
  • Dangling participle. "spending less time drafting" grammatically attaches to "this shift," not to "technical writers."
  • Redundant doublet. "fact-checking and validating" names one activity twice.

Suggested fix — use a figure the report actually contains:

The [State of Docs Report 2026](https://www.stateofdocs.com/2026/) found that 76% of
documentation professionals now use AI regularly, and that hallucinations are their
top concern at 62%. Writers are absorbing more verification work, and technical
writers report the smallest time savings of any role.


But manual verification has the same discovery problem as manual updates. You can't verify a page you don't know is wrong. [Making docs accessible to agents](/blog/technical/agent-friendly-docs-necessary-not-sufficient) is table stakes. Accuracy is the actual competitive surface.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — business-speak in a load-bearing sentence

"is table stakes" is business-speak, and "competitive surface" is not a phrase with a settled meaning. The reader cannot picture a surface competing.

Suggested fix:

Making docs readable by agents is the easy part. Keeping them accurate is what
actually separates you from a competitor.


A stale doc in your repository now affects every AI tool that ingests your codebase. The blast radius has grown from individual developers to every coding assistant those developers have installed.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggestion — inflated word choice

"every AI tool that ingests your codebase" → "every AI tool that reads your codebase."


## Closing the loop

The gap between a docs-as-code workflow and accurate documentation is a change detection problem. When code changes, something needs to identify which documentation that change affects.

Version control can't do this. It tracks file history, not semantic relationships between files and the product behavior they describe. Closing the gap requires a layer that understands what your documentation says and whether those claims still hold.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — one idea is stated six times across the article

The claim "version control cannot tell you which docs a code change affects" appears at :29, :45, :47, :49, :65, and :67. Lines 45 and 67 are near-verbatim duplicates in different sections. "Closing the loop" re-establishes the problem before proposing anything, so the section does not advance the argument until :69. A reader skimming hits the same sentence in three separate sections and learns nothing new.

Suggested fix: keep :45 and :47 as the full statement of the problem in "The synchronization problem." Cut this paragraph's first two sentences and open "Closing the loop" directly on what is required:

Closing the gap requires a layer that connects what your documentation says to the
changes that invalidate it.

Also (Suggestion) — borderline against the repo's banned-pattern list. "It tracks file history, not semantic relationships between files and the product behavior they describe" is the negation-contrast family the style guide bans ("X is not Y, but Z"), in its milder "A, not B" form. Cutting the sentence as recommended above resolves it. Flagging so it is not reintroduced elsewhere.


AI-powered documentation monitoring tools can detect these relationships automatically. When an endpoint is deprecated or a parameter is renamed, the tool identifies which pages reference it and surfaces them for review. The writer doesn't have to discover that anything changed. The change comes to them.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — the payoff paragraph leads with a four-noun stack and abstract verbs

"AI-powered documentation monitoring tools" stacks four nouns behind a marketing modifier; the style cheat-sheet flags 3+ stacked nouns. "surfaces them for review" uses "surfaces" as a vague verb. This is the sentence the whole article builds toward, and it is the least concrete sentence in the piece. Separately, "surfaces them for review" understates what the product does — Promptless drafts the edit and opens a PR rather than flagging pages.

Suggested fix:

Automated change detection closes this gap. When an endpoint is deprecated or a
parameter renamed, the tool finds the pages that describe it, drafts the corrected
text, and opens a pull request with citations back to the change that triggered it.
The writer reviews a proposed edit instead of hunting for what broke.


Docs-as-code and automated change detection are complementary. The workflow gets documentation into Git with a proper review process. Automated detection closes the synchronization gap the workflow leaves open.

@promptless promptless Bot Jul 28, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Important — the closing paragraph restates the article instead of ending it

All three sentences repeat claims already made (:19, :25, :49, :65). The repo's blog style guide is explicit: "Do NOT include a generic conclusion that restates what was said. The article should end with its final substantive point, followed by the <BlogRequestDemo /> component." Line 69 is the final substantive point.

Suggested fix: delete this paragraph. Cutting it costs the reader nothing and removes 33 words of restatement. If a closing beat is wanted, make it forward-looking and new rather than summarizing.


<BlogRequestDemo />
Loading