Muhammed Senussi
Muhammed Senussi
  • Muhammed Senussi
Technical Writing Is Storytelling With the Suspense RemovedStorytelling

The best documentation I have read was written by someone with a narrative instinct who knew exactly which instincts to suppress.

What transfers

  • A protagonist. Documentation has one: the reader trying to do something. Write from their position, not the system’s.
  • Cause and effect. "Set this flag" is a fact; "set this flag so requests are retried, which matters because the upstream service restarts nightly" is a chain a reader can remember.
  • Concrete over abstract. One real example beats three paragraphs of description, in fiction and in a reference guide alike.
  • Cut the throat-clearing. The first two sentences of most technical documents can be deleted without loss, exactly as in most short stories.

What does not transfer

Suspense. In a story, withholding information creates tension; in documentation it creates a support ticket. Put the answer in the first line and use the rest to explain it. A reader who came to find out how to rotate a key should have it before the paragraph on why key rotation matters.

1 Comments

  • Peter Bakker

    April 15, 2025

    Withholding creates a support ticket. I am putting that on the wall of our docs channel.

Leave a comment