One of Tom Fishburne’s Linkedin posts takes on a topic I’d wager you haven’t read much about: eminence-based marketing. Reading his post me think about how tech docs has its own version of this humorous approach to work.
The phrase Fishburne leans on 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 those alternative approaches describe approaches used by far too many documentation teams.
What follows is satire (plain and simple). Every person and scenario mentioned here is 100% invented. Any resemblance to your documentation team is coincidental. 🤣
Eminence-Based Documentation
In medicine, eminence means seniority outranks evidence. In docs, it means the writer outranks the product.
Consider this: Becky, a new technical writer, asks how her team knows whether an installation procedure she discovered is correct. The room goes quiet.
Eventually, a senior writer speaks up and declares,
“Martin wrote it.”
Becky asks who Martin is.
“Martin left in 2017.”
Since Martin left, the interface has been redesigned three times (maybe four) and the procedure tells users to select [Advanced Settings], a button that no longer exists.
After a long pause, another team member suggests users that encounter that procedure should probably submit a support ticket.
Becky soon learns the department’s standards of evidence:
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 she finds a 14-year-old comment in the source content:
<!-- DO NOT REMOVE THIS STEP. — MARTIN -->
Nobody knows what the step does or which Martin wrote it. There have, as it turns out, been three Martins (and one Martine) over those years. 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
The BMJ authors described vehemence as substituting volume for evidence. Documentation teams practice it; especially in review comments.
Here, the correct wording is whichever wording is defended in ALL CAPITAL LETTERS.
A reviewer signals mounting certainty with a second exclamation point, then with a snarky, “as I mentioned previously,” and finally by scheduling a meeting to discuss it. The Oxford comma thread reached 140 replies (no surprises there) and is now the longest-running project in the company.
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
The original paper said confidence-based medicine was limited to surgeons. In documentation, it’s limited to the engineer who built the feature.
“It’s intuitive. Nobody will need docs.”
When docs get written anyway, confidence-based documentation has a signature vocabulary.
“Simply configure your identity provider”
introduces a task that takes two days, four espressos, and a ticket to IT.
“Easily migrate your data”
is followed by 47 steps, three of them in a terminal window. The estimated-time label at the top of the page promises it will take about five minutes. Ha!
Release notes are the purest form of confidence-based documentation:
“Various improvements and bug fixes.”
Which improvements? The confidence speaks for itself. 🤠