Do That After This
By @edent
· documentation English language · 5 comments · 400 words
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.
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.
@Edent OMG yes, this sort of thing drives me nuts!
@Edent Pretty sure they made fun of this on MAS*H. They were trying to defuse a bomb and the instructions were like "Carefully remove explosive after having ensured blue wire is disconnected." Which of course they did the wrong way round.
@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.
@blog I have actually been genuinely impressed by some documentation I read recently: I commend the Luxon JavaScript date handling docs to everyone. The right amount of opinionated and sarcastic whilst not refusing to tell you how to do the thing they think you would be better off not wanting to do.
https://github.com/moment/luxon/blob/master/docs/why.md
More comments on Mastodon.