|
 |
Alternatives To Evidence-Based Technical Documentation
Three methods every documentation team uses and that no style guide addresses
|
| |||||||||||||||
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. Vehem