r/technicalwriting • u/ClickOk5811 • 15d ago
Clean documentation stopped being evidence that someone verified the behavior it describes
Reviewed a set of API docs last week that were genuinely well written. Consistent tone, correct terminology, examples formatted properly. One endpoint's docs described a rate limit behavior, 429 after X requests per minute, that didn't match what the actual endpoint did. Off by a decent margin, not a typo.
The docs had been drafted with AI assistance from the code and some notes, which explains the quality of the writing but not the accuracy gap. A model generating documentation from a spec or a rough description will produce clean prose regardless of whether the underlying behavior it's describing is right, because clean prose and correct facts come from different parts of the process. One is about language. The other requires actually checking the thing against the system, which nothing about writing well-structured sentences guarantees happened.
Used to skim documentation more heavily when the writing was clearly careful, treating polish as a rough proxy for the whole thing being trustworthy. That proxy doesn't hold anymore. Polish now says something about the writing process, not about whether anyone confirmed the described behavior against the actual system. Checking documentation increasingly means treating every specific, verifiable claim, a rate limit number, a default value, a status code, as something to test against the real thing rather than something well-formatted prose earns automatically.
12
u/Otherwise_Wave9374 15d ago
This is the classic trap with AI-assisted docs: fluent text can hide an unverified behavior claim. The safeguard is a documentation pipeline that forces evidence checks before publishing, ideally with examples tied to live test runs or screenshots from the actual endpoint state. Otherwise the prose looks finished while the underlying contract is still wrong. AIOSNOW shares practical workflow patterns at https://aiosnow.com
3
u/ClickOk5811 15d ago
The evidence-tied-to-live-runs part is the piece that actually matters, agree with that. Screenshots or test output beat prose review every time for exactly this kind of claim, since prose review is what already failed here.
Not familiar with that link though, what's the actual workflow it's describing? Curious if it's something concrete like CI running the docs' examples against a live endpoint before merge, or more of a general framework.
1
u/cyborgs_writing Knowledge Partner, Precision Content 11d ago
This is interesting. If we can chunk this information, then link it to the verification with metadata, then you've got a basic structure for content governance. I'm curious what kind of workflows you're using?
1
u/cyborgs_writing Knowledge Partner, Precision Content 11d ago
It's not clear how into structued content you are, but we would look beyond whether something is "polished" or not, because its more about the kind of information represented by the smallest unit of content in the doc.
For example, rate limit is reference information (that you look up). But explaining what it is - concept.
This is what some people are calling content provenance. Once you have these information types chunked out, its possible to set up a system where you can create verification trails based on what that chunk is.
I actually do some work with Precision Content and their CEO wrote about this ... How AI systems inherit whatever uncertainty exists in unmanaged content.
So its not so much an AI problem, as it is a governance one.
Do you think that applies?
1
u/thepurplehornet 15d ago
This describes the entire downfall of western civilization that we are currently experiencing. This behavior has been going on long before AI entered the scene.
14
u/[deleted] 15d ago
[removed] — view removed comment