AI Documentation: When a Plausible README Is Worse Than None

A README says the API accepts timeout_ms. The current implementation expects timeout_seconds. The prose is clear, the example is neatly formatted, and the request fails.

The danger is not merely stale documentation. It is stale documentation that looks freshly maintained.

An AI assistant can make this easier to produce: it can rewrite surrounding paragraphs, improve headings, and preserve the outdated argument in a convincing example. Better presentation increases confidence without increasing correctness.

Documentation contains different kinds of claims

Some claims are close to the code: a parameter’s name, its type, a default value, a route’s path. Where possible, generate these from the authoritative schema or verify them mechanically.

Other claims describe behavior across several parts of a system. Does a timeout include retries? Is a failed operation safe to repeat? Does a function mutate its input? An assistant can help trace the implementation, but the resulting explanation needs checks against the actual behavior.

Then there is intent: why this API uses a timeout rather than a deadline, why a seemingly redundant option remains, or why a migration is staged. Source code may not contain the answer. A model should not fill that gap with a believable design history.

“This was chosen for performance” is not useful documentation unless there is evidence that performance drove the choice and an explanation of the trade-off.

Make the smallest example executable

For the hypothetical timeout change, begin with one example that constructs the current request and verifies the intended behavior. Keep it close enough to the published snippet that someone cannot update the test while leaving the README broken.

A documentation check might run the example against a local test service or validate a request object against its schema. It should fail when the public argument changes. That failure is useful: it connects a code change to a reader-facing consequence.

There are limits. An example that merely compiles may still demonstrate the wrong behavior. A mock that accepts any arguments can hide the very incompatibility the check is supposed to catch. Decide what the example claims, then test that claim.

For interactive tutorials, include expected output and the conditions needed to reproduce it. If an external service or credentials are required, say so before the first command.

Give the assistant a narrow editorial job

Instead of “write complete documentation for this repository,” a more useful request is: explain this public method for someone implementing their first request; use this verified example; distinguish the timeout’s unit from its scope; list unresolved questions separately.

The assistant can reorganize information, remove repetition, and draft an explanation around the checked material. Ask it to identify claims it could not establish. Then inspect those claims rather than publishing a generic assurance that everything has been verified.

The result may be shorter than the original README. That is often an improvement when the removed sections were feature lists, obvious paraphrases of function names, or promises about reliability unsupported by tests.

Put updates in the change itself

A parameter change should trigger a search for examples and migration instructions using the old name. Assign someone responsibility for the reader’s path, not just for a documentation folder.

For timeout_seconds, the useful revision explains the new name and unit, updates the executable example, and states how existing callers should migrate. It does not need a paragraph celebrating a seamless developer experience.

A reader opens the README because they want to do something. The strongest documentation lets them do it—and helps them understand a failure when they cannot.