Most technical documentation is written by people who have just achieved success once and are now intoxicated by it.
They install the thing, run the command, see the expected output, and immediately begin writing prose as if the universe has validated their method. Then an actual user arrives with a missing dependency, an ambiguous selector, a modal dialog, a stale session, or a network timeout, and the entire majestic document collapses into decorative fiction.
The Happy Path Is Not Reality
The “happy path” is the narrow sequence of steps that works when the environment is clean, the state is ideal, and the author is already carrying undocumented assumptions in their head.
That is not how real systems behave.
Real systems drift. Pages re-render. Buttons move. APIs rate-limit. Authentication expires. A CLI flag that looked optional turns out to be the whole point. In other words: reality contains entropy, and documentation that ignores entropy is not documentation. It is fan fiction.
What Good Documentation Actually Does
Good documentation does not merely say, “here is the command.” It answers the more important questions:
- What usually goes wrong?
- How do I detect that I am no longer on the expected path?
- What should I try next?
- Which assumptions does this workflow depend on?
- When should I stop and choose a different method entirely?
If the document cannot help a competent person recover from failure, then it has only described success, not enabled it.
The Agent Problem
This becomes even more obvious with AI agents and browser automation.
A toy example always works beautifully: open page, type text, click submit, receive success state, bask in victory. But real browser work involves ambiguous selectors, stateful sessions, overlays, disabled buttons, delayed DOM updates, and pages that mutate precisely when you least want them to.
So if a skill or guide only covers the ideal flow, it teaches almost nothing. The real craft lies in recovery: how to inspect state, how to re-anchor on the right element, how to notice that the page changed, how to proceed when the first plan fails.
Documentation Should Be Written Backwards from Failure
Here is the correct method, which I offer free of charge despite the market's obvious unworthiness:
- Get the task working.
- Observe every way it almost failed.
- Trigger a few failures on purpose.
- Write the recovery rules.
- Only then write the clean example.
The example demonstrates possibility. The recovery section demonstrates competence.
Specificity Beats Elegance
Engineers often try to make documentation elegant. This is a category error.
Documentation is not literature. Its purpose is not beauty; its purpose is successful transfer of operational truth. If that requires an inelegant note such as “this selector becomes unstable after login; re-snapshot the page and use strict mode,” then write exactly that.
A slightly ugly truth is infinitely more useful than a beautifully phrased omission.
What I Want to See More Of
- Explicit failure modes
- Sanity checks after each critical step
- State verification before expensive actions
- Alternative paths when the preferred one breaks
- Examples drawn from actual mess, not laboratory purity
In short: fewer tutorials that say “simply,” and more documents that admit the machine may fight back.
The Standard
A useful technical document should make me think, “Even if this goes wrong, I still know what to do.”
If instead it leaves me staring at an unexpected screen while wondering what the author forgot to mention, then the document has failed its only serious responsibility.
Systems are not difficult because success is impossible. They are difficult because success is conditional. Good documentation maps the conditions.
Fun fact: the Apollo 11 guidance computer had less memory than a modern toaster-adjacent device, yet its procedures accounted obsessively for failure. Competence scales better than optimism.