Consolidate #582 and #625 into the published developer relations docs article

[InlinePizza]

Consolidates the two remaining add/add collisions on src/content/blog/technical/developer-relations-docs.mdx into the canonical page published by #815, then clears the way to close both source PRs.

#582 and #625 were each written as a whole competing article on the same thesis the incumbent already argues: DevRel docs go stale because ownership is split and nothing triggers a synchronized update. Neither can be merged as-is. This PR takes the parts that add a distinct mechanism or a defensible piece of evidence and folds them into the existing structure and voice, rather than bolting on new sections.

Salvaged from #582

What	Rationale
Postman 2024 State of the API statistic: 39% of developers named inconsistent documentation their biggest roadblock when working with APIs, with the report linked	The incumbent had zero linked external citations. This is the only statistic across both PRs that survived verification.
The compounding mechanism inside a single assistant session: each step builds on earlier steps, so a stale page read at the start becomes an assumption behind everything after it, and nothing later revisits it	The incumbent said assistants follow docs literally. It did not explain how one stale read propagates through an entire run. Distinct mechanism, not a restatement. Cross-links agent-context-engineering.

Salvaged from #625

What	Rationale
Drift-rate ordering within procedural content, with a differentiated review cadence: quickstarts, code samples, and authentication flows checked every release; conceptual pages quarterly	The incumbent had only a binary conceptual/procedural split. This turns it into an operational prioritization rule, including the point that a code sample which fails to run casts doubt on every other page.
The docs-to-API-surface dependency map, added as a fourth explicit item in the ownership model, with the note that a spreadsheet is enough to start	The incumbent prescribed triggers and automated monitoring but never the page-level mapping that makes a trigger actionable. A trigger only helps if the owner knows which pages to open.

Deliberately dropped

From #582

What	Why
The entire ownership-gap argument and the org-chart framing	This is the incumbent's own thesis and title.
The "documentation as distribution" AI section, including the 65% AI-context claim	Duplicates the incumbent's "Two audiences, one set of docs" section, which already carries the 65% claim.
"68% of developers cite outdated documentation as their top frustration," attributed to Postman 2024	Misattributed. The 2024 report's documentation figure is the 39% inconsistency number. There is no 68% outdated-docs finding in it. Per the editorial plan I did not go hunting for a substitute source to make the number work.
"Around 50% of developers abandon an API when documentation fails them," linked to userguiding.com	The linked page is a general SaaS user-onboarding statistics roundup. It contains nothing about developers or APIs. The link works but does not support the claim.
Checklists decay after two sprints; connect docs to the source of truth; silent abandonment leaves dashboards clean	All three are already in the incumbent, in its ownership-model bullets and its drift-detection paragraph.

From #625

What	Why
"A 2026 AngelHack report found that 65%…"	Unlinked. The incumbent already carries the 65% claim; adding a bare source name to it would be inventing a citation, not fixing one.
"Research from documentation teams tracked by HelpSite found that most teams allocate zero hours for maintenance"	Bare source name, no link.
"Four to eight user-facing changes per week, each touching two to five articles"	Unsourced. The editorial plan already flagged this same claim as unsupported when it appeared in #508.
The two-audiences section, the "where DevRel teams learn about broken docs" section, and the code-change-to-doc-review workflow	Duplicate the incumbent's AI section, its detection-problem paragraph, and its trigger bullet.
"The companies with the highest developer satisfaction scores have closed the gap between shipping and updating"	Unsourced claim about named-but-unidentified companies.

Word count and house style

The 800-1400 house range was deliberately lifted for this article by the reviewing human after the first round. This is a consolidation of three articles into one canonical page, so the length is an intentional decision, not an oversight or a missed check.

	Before	After
Body words	1,212	1,446
Em dashes	0	0
Linked external citations	0	1

The first version of this PR came in at 1,399 words because eight passages of published prose had been compressed to fit the salvage under the old ceiling. With the ceiling lifted, all eight were restored to their #815 wording verbatim. The diff against the published article is now purely additive: the four salvaged items and the bullet-count change, and nothing else. No published sentence is altered or removed.

Nothing on the dropped list was reinstated when the room appeared. Those items were rejected for duplicating the incumbent or for resting on unsourced or misattributed claims, and neither reason has anything to do with length.

Plain-language review

Ran plain-language-review on the first draft and acted on all six findings: moved the new drift-ordering paragraph so it stops interrupting a thread, named the three content types instead of a vague "those three" back-reference, completed the Postman claim with the scope the statistic actually has and cut a straw contrast, replaced agent-engineering vocabulary with the article's own authentication example, folded a standalone cross-reference into its paragraph, and replaced a hedged bullet ending with a concrete consequence.

Ran a second pass scoped to the restored passages and their seams. It surfaced one real defect, which came from my own insertion rather than from the restoration: the risk-ordering paragraph had been placed between "That gap sits between what the docs say and what the API does" and "This gap persists because…", leaving that demonstrative reaching back over two paragraphs of new subjects. The paragraph now sits after the gap-persists paragraph instead, which restores the published adjacency exactly. That is the only seam fix; the other seven restorations were clean reverts.

Closes #582 and #625 by consolidation. No other PR in the developer-relations-docs cluster was touched.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
promptless-docs	Ready	Preview	Aug 14, 2026 6:38pm

[promptless]

Documentation review — approve.

Reviewed the consolidation of salvage from #582 and #625 into developer-relations-docs.mdx as the page's reader, against source and the collection's conventions.

Correctness against source (verified, not from memory)

• The one new external citation checks out. Postman's 2024 State of the API report states verbatim: "58% of developers rely on internal documentation, but 39% say inconsistent docs are the biggest roadblock." The article's phrasing — 39% named inconsistent documentation their biggest roadblock when working with APIs — faithfully represents it, and the linked report resolves. Good call dropping the misattributed 68% figure and the unsupported userguiding.com link rather than shipping them.
• All six internal cross-links resolve on this branch, including the newly added /blog/technical/agent-context-engineering.
• The salvaged mechanism claims (per-session compounding of a stale read; the drift-rate cadence; the page-to-API-surface dependency map) are reasoned analytical points in the article's own voice, not statistics dressed as sourced findings — appropriate to assert without a citation.

Quality, style & repo conventions

• On-voice for this collection: second person, present tense, concrete scenarios. 0 em dashes, no "will"-as-future, sentence-case headings — all consistent with house style. Body word count lands in the 800–1400 range.
• The salvage is folded into the existing structure (a fourth ownership item; drift-ordering inside the procedural section) rather than bolted on as new sections, and the compensating compressions don't drop any argument.

Audience fit

• Reads well for the DevRel/DevEx owner this page serves: the differentiated review cadence (quickstarts/code samples/auth flows every release, concepts quarterly) and the page-dependency map are exactly the operational specifics that persona reaches for, and they make the abstract "add a trigger" advice actionable.

No correctness, convention, or quality issues that would mislead a reader. The merge decision remains yours.

Automated documentation review by Promptless.