Alternatives To Evidence-Based Documentation

One of Tom Fishburne’s Linkedin posts takes on a topic I’d wager you haven’y 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.

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.

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.