Organising technical documents for a good user experience

I was doing some technical writing at work recently, and I realised that I had automatically and unconsciously used a particular structure for the document.  It’s not something that geeks like me are always taught – I know it only because my Dad used to help people improve their technical writing.  So, in case it’s new to you, I’ll describe it here.

It’s called the inverted pyramid, although being a geek I think it would be better if it were called just the pyramid i.e. not inverted.  I’ll also describe why I think the pyramid is better the other way up, and how to use it.  Because I’m weird like that, I think it’s related to testing and to user experience (UX).

Sorting information by importance

The idea is that you present information in the order most important to least important. The pyramid is inverted because the width of the pyramid shows importance of the stuff in each sentence, which reduces as you go down the article.

If that description works for you, then great.  I prefer it to be the other way up, to look like real life pyramids:

When it’s this way up, the width of the pyramid shows how many things you have at that level.  It’s implied that the reason there’s only one thing at the top is because it’s the only one most important thing.  Below it in the pyramid / after it in the document are a few more things that are each a bit less important than the one first most important thing, and so on.

Structured like tests

This relationship where the number of things goes up as their individual importance goes down strongly reminds me of the testing pyramid.  (Another reason why I prefer the pyramid this way up.)  There are relatively few system-level tests, more integration tests, and even more unit tests.

The system-level tests each do big important things, like checking that a valid user can sign in and see their home page, or can check out a basket in an e-commerce site.  (You have only a few of them because they’re relatively expensive to create, run and maintain.)

As you go towards integration and then unit tests, the importance of each test goes down, but the number of them goes up.  This is because they each test a smaller and smaller bit of the system (so you need more of them to test everything you want testing) and they are cheaper and cheaper to create, run and maintain (so you can afford to have more of them).

Also, the test pyramid works because each level can rely on the lower levels.  Because they’re relatively cheap, and also because it’s easier to control the world around a unit test, it’s easier for a unit test to check rare things or fiddly details.  As the unit tests take care of this detail, the integration tests can afford to ignore the detail and concentrate on the world at a higher level (usually going away from the technology and towards the user).  If there’s a problem with an integration test, a common thing to do is to look down into the unit tests that cover the same area, to see if you can pinpoint the problem.

This is like the document pyramid.  The beginning parts of the document (higher up the pyramid) can ignore the detail to concentrate on the more important stuff, and this is possible because later parts of the document will handle the detail.

Why it’s useful – good user experience

If a user is scanning through documents, e.g. blogs on the web or finding something on an intranet, there’s a set of candidate documents, some of which will be useful and other less so.  How do you tell if it’s useful?

If the gist of the whole article is summed up in its first sentence (without any detail) then after reading only that one sentence you can decide whether to skip the article or move on.  You can quickly tell if it’s definitely wrong.

If you haven’t skipped to the next article after reading the first sentence then the article’s at least in the right area, but might be a near miss. That’s where the rest of the first paragraph comes in – it delivers the next level of detail down, to help the reader distinguish near misses from hits.

In short – it’s the way to help the reader be their most efficient.  It might not be software, but you can think of the reader as the user of the document.  Helping the user to be more efficient is nice from a user experience (UX) point of view.

Another way in which it can help the user is to present information such that bits you’ve already been told provide a framework on which you can hang the later bits as you read them.  This helps you integrate the parts of the document in your mind, rather than being bewildered by a blizzard of detail with no obvious structure behind it.

Walking the talk

I don’t always follow this approach to the letter – first sentence / first paragraph / rest. For instance, in this article the first sentence doesn’t sum everything up. However, I do usually think about the introduction. It’s not a useless thing tacked onto the top, or a tedious extra chore to get through. It’s effort you put in because you want to treat the user / reader well, just as you hope the people writing the things you read will treat you well. (Who likes reading stuff that’s hard to read?)

Also, you might be wondering why there’s a summary or conclusion on many blog posts. This doesn’t seem to fit into the pyramid structure, as it’s like a mirror of the introduction. If anything, it would make the structure into a diamond shape as it narrows down again.

I do this for another UX reason. If the user has taken the time to read the article, I want to make that time as productive for them as possible, by helping them to remember what they’ve read afterwards. To do this I use the tell them, tell them, tell them approach that’s often useful in writing or presenting:

• Tell them what they’re about to read / hear – the introduction teeing up the bulk of things.
• Tell them the bulk of things – the rest of the pyramid
• Tell them what they’ve read / heard, by reminding them of the top of the pyramid now that we’ve gone through all the details of the lower part of the pyramid. Just recapping the top of the pyramid can help them to remember the detail too, as the top layers provide a mental framework that gives the detail a sensible place to live.

How to use it

Maybe I’ve convinced you that this could be helpful at least in some situations, but you’re a bit unsure as to how to write this way.  I have a suggestion, that I will illustrate using some silly examples.

The document you’re trying to write is about some idea, for instance what a software tool is and how to use it.  The document expresses that idea in words (duh!).

To write the first sentence, imagine that you need to express the idea, but I have given you a budget of only one sentence’s worth of words.  It’s a normal length sentence, rather than a nonsense mission-statement length one.  You must limit yourself to only the most important parts of the idea – the bits that most effectively make it different from all other ideas.  (If it helps, think about entropy.  I realise that this probably won’t help most people, but I’m mentioning it for the few that it might.)

I’ll assume that you’ve written the first sentence.  It’s now time to move onto the rest of the first paragraph.  You still need to express the idea, you have the first sentence in the bank, and I’m now increasing your budget to one paragraph’s worth of words (minus one sentence).  Again, it’s a normal length paragraph rather than a huge one.

Then, when the first paragraph is out of the way, things get a bit more free form and hard to predict.  It might be that there’s not much left to explain, or it could be that there’s still loads of detail.  It might be helpful to continue working through levels of detail, or it might be better to break it up by topic, by person, by time or some other organising thing.  I’m afraid I don’t have any suggestions here other than to think about the likely user / reader of the document, and what would help them.

Silly examples

I’ll bring in the silly examples now, which are in case this notion of word budget is unhelpful, and too much like word count for essays you’ve wrestled with in the past.  Think of the word budget in terms of time – assuming a normal and constant rate of speech – the more time you have, the more words you can say.

For the first sentence, imagine the person you want to talk to / write the first sentence for is in a lift (and you’re in the hall outside the lift) and the doors have just started to close.  You have only a few seconds before the lift takes them away and you need to tell them the thing.  Fortunately, unlike with lifts about to leave, as a writer you can take time to think about and revise things, but you still have only the lift doors closing amount of time to get the idea across.

For the first paragraph, imagine that this person has gone on to catch a train and you’ve caught up with them at the station.  You’ve already told them the sentence as the lift doors closed, so you don’t need to repeat that.  However, you catch up with them shortly before the train’s due to leave.  You have a small number of minutes, maybe only one or two.  Again, unlike with the lift, you have time to think about and revise things, but you need to continue explaining the idea in only one or two minutes.

As for the rest of the document, you’ve met up with the person for a third time, and now you’re sitting down with them.  Are you sitting down for a quick cup of tea on a tea break, or is it a leisurely dinner?  I don’t know.  This is where things are more open-ended and harder to predict.

Summary

One way to structure documents, including technical documents, is to present information in the order most important to least important.  This can be thought of as a pyramid, either inverted (where the width shows importance per sentence decreasing as you go down the document) or the right way up (where the width shows the number of things with the same importance increasing as you go down the document).

This is often a better user experience for the reader, as it helps them to decide between documents most efficiently, and helps them make sense of the document without having to read it more than once.

When you’re writing in this way, you can think of having a word budget that increases as you go down the document, that you can spend to express the remaining bits of the idea.