A recent Marketoon post by Tom Fishburne takes on “eminence-based marketing,” and in addition to making me giggle, it also made me think tech docs has its own version. The phrase Fishburne discusses comes from medicine. In 1999, two physicians published a tongue-in-cheek British Medical Journal paper listing seven alternatives to evidence-based medicine. Three of them describe technical documentation types uncomfortably well.
🤣 What follows is satire. To show how these methods work in practice, I invented a software company and gave it a documentation team. The company and everyone in it are fictional. Any resemblance to your team is purely coincidental.
Eminence-Based Documentation
At our fictional software company, a new tech writer, Becky, asks if anyone can tell her how to find out if an installation procedure is correct.
The room goes quiet. Eventually, the senior writer says,
“Martin wrote it.”
She asks who Martin is.
“Martin left in 2017.”
The interface has been redesigned three times since then, and the procedure still tells users to click Advanced Settings, a button that hasn’t existed for years. After a long pause, someone suggests users should probably submit a support ticket.
Becky soon learns what her department’s standards of evidence are:
If a developer said it, it’s probably true.
If a senior developer said it, don’t question it.
If a step appears in more than one manual, that counts as peer review.
If Martin wrote it, it’s a requirement.
If nobody knows why something is documented, it’s called institutional knowledge.
Then Becky finds a 14-year-old comment in the source: <!-- DO NOT REMOVE THIS STEP. — MARTIN -->. Nobody knows what the step does or which Martin wrote it. There have, it turns out, been three Martins in that time. The team agrees not to touch it, which is how a workaround for version 4.2 became company policy in version 11.
Evidence-based documentation asks what the product does. Eminence-based documentation asks who you are to question Martin.
Vehemence-Based Documentation
At our fictional company, vehemence lives in review comments, where the correct wording is whatever someone defends in capital letters. A reviewer signals mounting certainty with a second exclamation point, then with “as I mentioned previously,” and finally by scheduling a meeting. The Oxford comma debate reached that last stage two years ago. It’s now a standing meeting with no decision in sight.
The style guide reserves Danger for situations that could cause serious harm. Vehemence-based documentation reserves it for the reviewer who replied in ALL CAPS.
That’s how a mildly inconvenient default setting ends up with a bold red Danger label while the step that deletes the user’s data gets nothing, because nobody argued about it.
Confidence-Based Documentation
At our fictional company, confidence-based documentation is restricted to the engineer who built the feature, much as the BMJ paper restricted confidence-based medicine to surgeons. “It’s intuitive,” the engineer says. “Nobody will need docs.”
When docs get written anyway, the confidence shows up in the adverbs.
“Simply configure your identity provider”
introduces a task that takes two days and a ticket to IT.
“Easily migrate your data”
is followed by 47 steps, three of them in a terminal.
The estimated-time label at the top of the page promises it will take about five minutes. The fastest recorded time, set by the engineer who built the feature, is four hours.
Release notes are confidence-based documentation in its purest form:
“Various improvements and bug fixes.”
Which improvements? The confidence speaks for itself. 🤠