Do That After This


I was building some flatpack furniture the other day (my life is so glamorous) when I came across an interesting example of how not to write technical documentation.

Drill a hole in part A and insert part B once you have ensured part C has been aligned after its connection to A.

Most people can handle reading a whole sentence to figure out what's going on. But, after a tiring day of building, it is somewhat annoying having to juggle instructions into actions.

Most readers will assume that instructions are written in linear time. Do this, then that. But that example is non-linear. What it is trying to say is:

Connect part C with part A. Then align part C and part A. Then drill the hole in part A. Then insert part B into part A.

It is slightly less interesting writing. But it presents all the actions in the order they need to be taken.

I see this temporally-mixed anti-pattern all the time. A typical example of this in technical documentation is:

Select Print from the File menu.

A simpler, clearer, and less ambiguous way of writing that is:

Open the File menu. Select Print.

Another similar example of confusing writing is:

Go to File → Print → Settings if you need to change the paper size.

Again, this places cognitive burden on the reader. If they want to understand if the instruction is relevant to them, they have to read the entire sentence. When faced with dozens of sentences, this can become confusing. The solution is:

If you want to do X, then do Y...

Immediately the reader knows that they can skip this sentence because they don't want to do X.

As technical writers, we sometimes want to craft eloquent prose. We long for glorious and intricate sentences. We tire of the monotony of linear writing.

Tough. We need to get over ourselves. Go write that epic fantasy novel you've been thinking about. The job of a technical writer isn't to entertain, enliven, or delight the reader. The job is to give them instructions in an easy to follow format, reducing the amount of cognitive burden they have, and making it quick to find the information they need.


Share this post on…

5 thoughts on “Do That After This”

  1. I've seen this so often when testing documents, forms, and other technical instructions.

    And teaching 'if before then' and other 'put in logical order' techniques for at least 20 years - as in my website editingthatworks.com - see technique 6.

    Reply
  2. @blog I draw a distinction between reference documents - which need to be repetitive and formulaic and when you look up X the full details of X are there and it doesn't send you down a rabbit hole chasing references - and getting started / training documents, which need to tell you the story of how you do the thing and why you should care.

    | Reply to original comment on mastodon.social

What are your reckons?

All comments are moderated and may not be published immediately. Your email address will not be published.Allowed HTML: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong> <p> <pre> <br> <img src="" alt="" title="" srcset="">