Documentation that tells a story

When reading technical documentation I too often come across examples like this:

let’s assume you have a client called foo and a server called bar

or command examples like:

mysqldump -h server1 | mysql -h server2

When I write documentation, I prefer to tell a story. What is the client called, Steven? Are we taking a mysqldump of a production server and writing it to a staging server?

Human brains like stories. It’s much easier to keep track of facts if they have some kind of meaning. Many memory improvement techniques use stories to link things together. And when you’re reading documentation, you’re usually learning some new concept anyway – so you’re adding unnecessary cognitive load by using abstract labels like Foo and Bar or A and B.

In my Git submodules post I name the two example projects your_project and other_project and use it consistently throughout. You never have to rememeber whether “Foo” is the remote project or not.

One of my own favourites is an old heartbeat cluster guide I wrote. It involves two clusters, each of which consisted of two servers working together. I named the first cluster JuliusCaesar, naming the two nodes Julius and Caesar. The second cluster is called MarcusAurelius. Throughout the documentation, I’m able to refer to any server just by it’s name and you can know where it is in the network.

It’s part of why I like using rspec to do testing, because it encourages you to tell a story rather than to just test arbitrary values.

So, put some thought into your examples. Tell a story. Make it easier for the reader to keep track of all this new stuff they’re learning.


You would enjoy attending a talk by David Snowden, if you get the chance. (
His theories in this area are proven time and time again through his talks, and not only that, the anecdotes included are fantastic ways of reinforcing the point.

Humans don’t remember facts, they remember stories.
Why else do teachers recommend putting stories to acronyms?

Ed Davies says:

Indeed. However, don’t get so wound up about the story that it becomes a distraction – adding gobs of text irrelevant to the main theme or distorting the way things are presented to fit the plot. I’d suggest that if you’re adding more than the odd sentence here or there for motivation then it’s time to cut back. Your project and cluster server names are good examples because they don’t need any explanation at all.

I gave up on one programming language book because the story part was so distracting. I later learned the language in question from a Nutshell book.

Oren says:

You might find this interesting:
Still work-in-progress, of course…

Simon says:

I don’t know what the client is called and why are you calling me Steven?

Leave a Reply