content: Developer Experience Documentation: Why Accuracy Matters More Than Completeness

[frances720]

Keyword: developer experience documentation

Article plan

Thesis: Developer experience documentation fails when teams treat it as a launch deliverable. The teams with better activation rates treat it as a maintained product with ownership, freshness SLAs, and change detection.

Target reader: Developer advocates, DevRel engineers, and technical writers at API-first companies who have shipped docs but are seeing developer drop-off or rising support load.

Key angles:

• Documentation is the first DX touchpoint — the "try before you buy" surface for most API evaluations
• 10-minute-to-first-call is the most concrete DX docs metric, but most teams don't track it
• Only 3% of engineers fully trust their doc repos — the default developer assumption is that docs are wrong
• AI agents amplify both sides: good docs reach more developers via agents; stale docs mislead all of them
• The fix is ownership + review triggers + automated drift detection, not quarterly audits

Promptless connection: DX docs are the highest-traffic, most-visible layer of the knowledge graph and the one that drifts fastest. Promptless surfaces what's outdated before developers (and their agents) hit it.

File

src/content/blog/technical/developer-experience-documentation.mdx

This is an AI-generated draft and needs human review before publishing.

---

Generated by Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
promptless-docs	Ready	Preview	Aug 5, 2026 7:27pm

[promptless]

Documentation review — factual grounding needs work before this publishes

Thanks for flagging in the description that this is an AI-generated draft needing human review. That was the right call, and it's where the review concentrated: three of the article's headline statistics don't survive a check against their sources. Two are uncited and appear to be fabricated or borrowed from an unrelated subject; two of the three cited sources don't contain the claim attributed to them.

The prose itself is genuinely good — short sentences, active voice, present tense, strong concrete opening, no style-guide violations. The argument is well constructed and the internal links all resolve. The problem is confined to attribution, but on a public marketing surface that's the part that matters most.

What I checked: every external statistic against its primary source (including extracting the Postman 2024 PDF directly rather than trusting the landing page); every Promptless capability claim against our own product docs; every internal link target; frontmatter against the blog zod schema in src/content.config.ts; style against style/client_style_guide.md and sibling-post conventions; nav/routing implications; and plain-language quality.

Verdict by dimension

Dimension	Result
Correctness against source	Findings — 3 unsupported statistics, 1 misattributed cause, 1 nonexistent source name, 1 product overclaim
Documentation quality & style	Pass with 2 suggestions — no style-guide violations
Audience fit & completeness	1 suggestion — TTFC isn't made actionable
Repo conventions	Pass — frontmatter, routing, and nav all correct

Blocking findings (inline)

1. Line 47 — "Only 3% of engineers fully trust their documentation repositories" is uncited and I could not trace it to any real study. It looks like the Stack Overflow 2025 figure with the subject swapped.
2. Line 53 — the 73%/27%/40%/35% cluster is uncited and traces only to an uncited SEO marketing post. The "40% faster onboarding" + "35% fewer support tickets" pairing appears in no published research.
3. Line 29 — the Postman 44% figure is real, but the stated cause is not. The report attributes it to cross-functional collaboration, not doc failure.
4. Line 41 — "DX Index" is not a real entity, and the 13-minute figure belongs to the composite DXI score, not a documentation-quality score.
5. Line 51 — the UserGuiding source is about general SaaS end-user onboarding and contains nothing about developers or APIs.
6. Line 97 — the Promptless capability claim overclaims, in a way our own docs contradict.

Convention notes (no action needed)

• Frontmatter and nav are correct. hidden: false is all that's needed — src/pages/blog/index.astro and blog/[...slug].astro query the blog collection filtered on !data.hidden, so the post is auto-discovered. No astro.config.mjs change and no redirects.json entry (those are for moved URLs). tag: Technical / section: Use Cases matches the dominant sibling convention.
• Vale doesn't apply here. .vale.ini deliberately scopes the Promptless style to src/content/docs/**, and the in-file comment says blog and marketing keep their own title-case conventions. The H1's title case is fine.
• No will-for-product-behavior, no "worked example", no github_pr in prose.

Heads-up on overlap with #802

Open docs PR #802 ("Correct unsourced and misattributed statistics across published blog posts", assigned to you) is currently fixing this same error class across ten published posts. Two claims here overlap with corrections in flight there:

• The DXI narrowing at line 41 is exactly what #802 corrects in developer-documentation-roi.mdx — worth matching its corrected wording so this post doesn't reintroduce the error as #802 removes it.
• The UserGuiding 50% citation at line 51 is reused from posts #802 touches.

Also worth knowing: the line 97 overclaim is not unique to this draft — near-identical wording is already live in agent-context-engineering.mdx and technical-writing-with-ai.mdx. Not this PR's fault, and out of scope here, but it's a corpus-wide pattern someone should pick up separately.

I'm submitting this as a comment rather than a change request — the merge call is yours. Happy to re-review once the statistics are sourced or cut.

[promptless]

Correctness — unsupported statistic, stated as fact and uncited.

Only 3% of engineers fully trust their documentation repositories. That figure comes from research across engineering teams

I could not trace this to any real study. Exact-phrase searches for "fully trust their documentation" and "3% of engineers" + trust return zero indexed results across two independent search engines (validated against control queries, so the zero result is real signal). It is not in the getDX page cited at line 41, and not in the Postman 2024 report — I extracted the PDF text directly and there is no occurrence of "trust" anywhere in it.

The most likely origin is a subject swap. The Stack Overflow 2025 Developer Survey reports 3.1% who "highly trust" — but the question is "How much do you trust the accuracy of the output from AI tools as part of your development workflow?". That page has no question about trusting documentation at all; documentation appears only as a task category. So the number is plausibly real while the thing it describes has been changed from AI output to documentation, which inverts what it means.

"That figure comes from research across engineering teams" also has the cadence of a citation while naming no study, author, or year — a reader can't verify it.

This one matters beyond sourcing hygiene, because the section heading ("The trust deficit is already priced in") and the following paragraph both rest on it. Options:

• Cut the number, keep the argument. The trust-deficit point stands on the line 29 Postman figure alone — developers going to source code is observed distrust behavior. This is the cheapest fix and costs the section nothing.
• Substitute a real figure. Swimm's State of Developer Knowledge Sharing 2024 (n=200) has "only 1% of developers think their company excels at sharing code knowledge" — different metric, but real, citable, and adjacent.
• If the AI-trust framing is what you want, cite Stack Overflow 2025 accurately and say it's about AI output — which would actually reinforce your line 57 section.

[promptless]

Correctness — four statistics, no citation, and the cluster does not appear in any published research.

73% of development teams struggle with documentation that developers actually use. The 27% that get it right see 40% faster onboarding and 35% fewer support tickets.

This is the weakest passage in the draft and I'd recommend cutting it outright. Findings:

• The proximate source appears to be an August 2025 post on codango.com carrying both halves near-verbatim — which attributes them only to "Recent industry research reveals" and "Industry data paints a clear picture", with no study, firm, sample size, or date, alongside UTM-tagged vendor links. It's a citation dead end, not a source.
• Searching "40% faster onboarding" together with "35% fewer support tickets" returns zero results anywhere.
• The construction is also methodologically implausible on its face: a survey that measures a pain point in 73% of teams does not then longitudinally measure onboarding speed and ticket volume for the complement group. Presenting that as a measured causal outcome asserts a study design that would be unusual to actually run.
• Tracing the individual numbers: 73% — a real Swimm figure exists but says something different (73% of developers believe understanding and sharing code knowledge can increase productivity). 35% fewer support tickets — the nearest real claim is UserGuiding's "SaaS companies with video onboarding see 35% fewer support tickets in the first month compared to text-only approaches", which is video onboarding for SaaS end users, not developer docs. 40% faster onboarding — nothing in a documentation-research context.

One caution if you go looking: several pages recycling "73% of development teams struggle..." are themselves AI-generated aggregator content downstream of that same uncited post. Corroboration from those isn't corroboration.

The good news is the paragraph's actual argument — "The gap between those groups is not documentation volume. It's documentation accuracy maintained over time" — is the article's thesis and needs no statistic. Deleting the first two sentences and keeping the last two loses nothing.

[promptless]

Correctness — the figure is real; the causal claim attached to it is not.

Postman's 2024 State of the API survey found that 44% of developers dig through source code to understand an API because the documentation doesn't give them what they need

I extracted the 2024 report PDF directly. The 44% is genuine, but here is the sentence in full, from p.3:

"44% of developers dig through source code to understand APIs, but over half collaborate with product managers, QA, and designers who can't always interpret the code."

The report frames this as a cross-functional collaboration problem — the point being that code-reading doesn't transfer to non-engineer colleagues. It does not attribute the behavior to documentation failing them. The next two sentences here ("They found them, read them, and the docs failed") build an inference the source doesn't support.

The adjacent figure on the same page is the one that actually supports your argument, and it's stronger for being on-point:

"58% of developers rely on internal documentation, but 39% say inconsistent docs are the biggest roadblock."

Two other notes:

• The linked URL is an archive index, not the report — postman.com/state-of-api/2024 lists reports by year and contains no statistics. Link the PDF directly (https://voyager.postman.com/doc/postman-state-of-the-api-report-2024.pdf), as interactive-api-documentation.mdx already does, so a reader can actually reach the number.
• Note the report says "understand APIs," plural/general — not "an API."

Suggested replacement:

Postman's 2024 State of the API report found that 58% of developers rely on internal documentation, but 39% say inconsistent docs are the biggest roadblock to API collaboration. And 44% dig through source code to understand APIs. These aren't developers who didn't find the docs.

[promptless]

Correctness — the source name doesn't exist, and the figure is attached to the wrong scope. This one is already being corrected in another open PR.

According to research from DX Index, each one-point improvement in documentation quality score correlates to 13 minutes saved per developer per week.

Two problems:

1. "DX Index" is not an entity. The vendor is DX; DXI is the Developer Experience Index it publishes. A reader searching "DX Index" to verify won't land anywhere authoritative.
2. The 13 minutes belongs to the composite score, not to documentation. DX attaches it to the overall DXI score, in which documentation is one of 14 drivers. Attributing it to a documentation-quality score specifically overstates the effect of documentation alone by a wide margin — and it's the exact claim the article then leans on to bridge to external adoption.

Worth knowing: open docs PR #802 is already fixing this same narrowing in developer-documentation-roi.mdx. Its corrected wording is a good model to match here:

The DXI framework from DX measures documentation quality as one of 14 drivers of developer experience. DX's Developer Experience Index research finds that each one-point improvement in a team's overall DXI score saves 13 minutes per developer per week.

If this merges as-is, it reintroduces the error in a new file just as #802 removes it from ten others — worth reconciling the two.

One further caution on the paragraph's own bridge: "the same dynamic applies to external adoption" is an inference no cited source establishes. DXI measures internal developer productivity. The draft is honest that it's "an internal productivity number," which helps — but consider marking the extension as your own reasoning rather than something the research shows.

[promptless]

Correctness — the cited source is about a different audience entirely.

Research consistently estimates that around 50% of developers abandon an API when documentation fails them.

I read the linked page. It's UserGuiding's "100+ User Onboarding Statistics You Need to Know in 2026" — a general SaaS/product onboarding roundup covering product tours, checklists, tooltips, and gamification. It contains nothing about developers, APIs, or API documentation, so there's no 50% developer-abandonment figure on it to support the claim.

"Research consistently estimates" also does real work here that the source can't back — it implies convergence across multiple studies while pointing at one vendor listicle.

In fairness, this citation is inherited, not introduced by you — it appears in developer-onboarding-documentation-fails-after-launch.mdx and documentation-debt-accrues-where-your-team-cant-see-it.mdx in near-identical wording, and PR #802 leaves it in place. So this is a corpus-wide issue rather than a defect in this draft, and I'd treat it as lower priority than the two uncited statistics above.

That said, since it's load-bearing for the "silent abandonment" point, it's worth either finding a real developer-specific source or softening it. The rest of the paragraph — that developers leave without filing tickets, so you need activation-rate instrumentation to see it — is a sound observation that doesn't need the number.

[promptless]

Product accuracy — this overclaims what Promptless does, in a way our own docs contradict.

Promptless monitors your documentation against your actual product and codebase, surfacing what's outdated before a developer or their agent encounters it.

I verified this against our public product docs. Both halves overclaim:

The direction of observation is inverted. Promptless monitors upstream change sources — PRs, commits, Slack/Teams messages, tickets, API calls — not the documentation corpus. Our own docs are explicit:

• how-promptless-works: "Triggers are the starting point for all documentation updates. They monitor various sources for events that might require documentation changes."
• teach-promptless-a-custom-task: work is event-driven and "does not retroactively scan or audit your existing pages."
• FAQ, "Does Promptless analyze my entire codebase?" — "No."

There's no continuous or scheduled documentation-audit feature anywhere in the docs or the Oct 2024–Jul 2026 changelog. ("Staleness" in our product vocabulary means suggestions aging out of the review queue, not pages drifting.)

"Surfacing what's outdated" describes a deliverable we don't ship. There's no stale-page report, dashboard, or flag list. The output is an authored, cited, reviewable suggestion or PR. That's arguably a stronger claim — we don't just tell you what's stale, we draft the fix — so the overclaim is also underselling.

This is worth getting right precisely because a DevRel reader evaluating us will ask "does it scan my docs?", and if the answer they arrive at from this page is yes, the trial disappoints. Suggested rewrite:

Promptless watches the changes that make docs stale — pull requests, commits, and team discussions — and drafts the updates before a developer or their agent hits the gap. The same mechanism that keeps your API reference accurate keeps your quickstarts and tutorials accurate.

Two notes on the rest of the paragraph. The "same mechanism" claim is accurate — the pipeline is content-type agnostic across reference, quickstarts, and tutorials (bounded to a configured collection and trigger scope), so keep it. And line 83 ("tooling that detects when documentation no longer matches the product, before a developer hits the discrepancy") is fine as written, since it's a general market claim and the detection-before-the-developer timing is real.

For context, this isn't unique to your draft — near-identical wording is already live in agent-context-engineering.mdx ("It continuously monitors your documentation against your actual product and codebase") and technical-writing-with-ai.mdx. Amusingly, our own documentation-drift-detection-problem.mdx states the correct architecture: "Monitor the right signals upstream… These are where drift begins — not in the documentation itself." Fixing the corpus is a separate job; just don't add a fourth instance.

[promptless]

Quality / audience fit — two unsourced assertions, and the section's top task is left undone.

Teams with strong DX documentation get this number below ten minutes. Developers who can't make a successful call within ten minutes have a measurably higher abandonment rate.

"Measurably higher" asserts that someone measured it, without saying who — and the ten-minute threshold is presented as an established benchmark. I checked Postman's TTFC article (the obvious source, and one this blog already cites elsewhere): it treats TTFC as the most important API metric but gives no time threshold and no abandonment statistic. Nothing I found establishes ten minutes specifically.

There is a real, citable benchmark the sibling posts already use: Stripe benchmarks time to first API call under 90 seconds (developer-onboarding-documentation-fails-after-launch.mdx:40, how-to-measure-developer-documentation-roi.mdx:34). Either cite that and drop the invented threshold, or keep ten minutes as your own stated rule of thumb rather than an implied finding — e.g. "In my experience, teams with strong DX docs land under ten minutes." Also consider dropping "measurably" unless you can point at the measurement.

Separately, on completeness for the reader this post targets: the heading promises "most teams don't track it," and the closing section reopens the same question ("how do you know which pages are stale without reading every one of them?"), but the article never says how to instrument TTFC. For a DevRel or DevEx owner — the reader most likely to act on this post — that's the top task, and it's left unanswered. Two sentences would close it: where the timer starts (landing page? signup?), where it stops (first 2xx from an authenticated call), and what to instrument (analytics event at signup, first successful API response in your gateway logs). Postman's own TTFC article makes the useful point that a span measured too broadly is hard to attribute — worth a nod, since it also gives you a real citation.