How to Write Good Instructions
You’re not gonna like it.
For something to be good, it should fulfill its purpose. What is the purpose of giving instructions? Not for our own health. Teaching someone how to do something can take twice as long as doing it ourselves, and that’s if they get it right the first time. On top of unpaid babysitting, it’s also giving away precious experience that we had to learn the hard way. Nothing personal, just bad for business.
This collective action problem — a selfless act that only pays off if everyone does it together — hinders so much progress.
Given enough time, most people can fumble through tasks of reasonable difficulty, learning through trial and error and asking questions as necessary. But then, everyone is just reinventing the wheel in their own silo. What an inefficient way of running an organization, and also sad! Especially as a young person, what’s the point of joining an organization if you’re still alone? We are not fish; we don’t sink or swim on feral instinct after hatching from an egg. We are complex social creatures, not rodents who eat their young. Alone, we can only grope along day after day, muddling through a fog of guesstimates and blunders, fearful of asking too many questions and incurring wrath, or giving the wrong answer and getting smited as by a Sphinx, subsisting on the charitable knowledge of a few good Samaritan coworkers, but terrified of being sent to the poorhouse for daring to ask for help. But this dereliction settles like a bad look on everyone. Just like how we try to give homeless people one-way bus tickets out of town, we scramble to cover up anything that makes us look or feel dysfunctional, even when it’s not an immediate threat, because deep down, we know there’s something wrong with being heartless. One day, after years of insidious corrosion to our guilty consciences, that is when we wake up to find everything gone wrong. The solution is to do better.
The purpose of giving instructions is to save time and energy; first, for other people to succeed at their jobs, then, for ourselves to more efficiently cooperate with the people we’ve trained. The end goal: finish the work with lower cost and better results than if we did it alone, and then we all go do better things with our time. Everybody wins.
If the measure of good instructions is to save other people time and energy, then instructions need to do three things. First, teach people how to do something by answering all the questions needed for the task. Second, make life as easy as possible by imparting knowledge at the right place and time, not just dumped all together. Third, minimize unnecessary errors and stress by being clean and easy for the eyes to read.
1. Answer All Potential Questions
In an ideal world, there would be no follow-up questions because the instructions would answer all of them. That’s the whole point. At least, a sure sign that you haven’t done your job is if the audience still has a lot of basic questions after you’ve already instructed them, forcing them to do your job for you.
Start with the big picture. From a bird’s eye view, what is the overall goal and how does this particular task fit into that vision? A one or two sentence summary will do. This basic premise should not trigger an existential crisis. If it does, you’ve got a bigger problem, and you shouldn’t move on until you address it.
Identify your audience. Which specific teams and individuals will be reading and using these instructions? Who else might use them in the future? Will there be indirect effects on other work processes or people?
State a clearly requested deliverable. At the top of the document, in one or two sentences, state what exactly you want to have in hand by the end of the project. A memo, spreadsheet, email summary, verbal answer, or anything similarly discrete and concrete would be great.
Give numbered how-to steps from start to finish. Keeping your audience in mind, give numbered steps for completing the task. The numbers will make it easier for people to check their own work (to confirm they’ve done 6 out of 6 steps, or 13 out of 13 steps, etc.).
Link all the tools needed to complete the job. Don’t be shy about copying and pasting hyperlinks to all the folders, websites, databases, tools they’ll need, including:
Raw data — Remember to grant access permission if the system requires it.
Reference materials, academic articles, background reading
Previous history of the project — Previous work, templates, emails, memos, and records that are relevant. If there is a particularly relevant template or record, be sure to draw attention to it.
People contacts — Use generic team emails and phone numbers wherever possible, since individual people come and go often.
Tools — List of/links to the tools needed for the job, along with the necessary username and passwords, and any instructions for using the tools. Remember to grant access permission if the system requires it.
Where to save the work — Nothing matters if you can’t locate the work product in the future when you need it!
2. Give Information in the Right Places
Different languages are read in different directions, but almost universally, they flow from one end of the page to the other. Scrolling up and down, back and forth is nobody’s idea of a good time. Therefore, information should be organized in the order that the audience needs it. If you’re really ambitious, count how many mouse clicks and back-and-forth scrolls or page flips it takes to go through your document. How annoying does it feel to be your reader?
Start with items that require lead-time. Just like preheating an oven, tasks that require waiting for other people or waiting for a machine to finish doing its work should come first because they are outside of our control. We don’t want to end up finishing our own work first but be unable to go home because we’re idling around for someone else. This includes requesting access permission to work tools, since we can’t start anything without them.
A place for everything and everything in its place. It’s very tempting to add a stray note when we suddenly remember something. However, unless you are an old-fashioned professor with invincible tenure, you are henceforth banned from using footnotes! Information is binary; it’s either relevant or not. If it’s relevant, then find the appropriate place for it in the body of your text and keep it there. If it’s not, then delete it because it’s just a distraction.
Parentheticals (putting something in parentheses) and random side notes with asterisks * are also very dangerous because, just like footnotes, they seem unimportant and your eyes are inclined to gloss over them, but in reality you could be missing something critical. If someone makes a mistake because they missed the fine print, they’d feel silly and demoralized, and it creates that much more trouble for everyone. If you use these, consider them truly extra. Assume that nothing in your parentheticals, footnotes, or side notes is being read, and if the text still stands, then you can proceed.
Break out your text into multiple documents for a side-by-side view. Sometimes, a lot of text needs to be viewed concurrently and there’s no way to fit it all. In that case, break it out into multiple documents so you can view them with side-by-side windows.
As a last resort, use cross-reference links. Links like “Jump to Recipe” and “Back to Top” allow you to jump to different sections within the same document. Every word processor can create these links. As a last resort, if you’re not able to break out your information into multiple documents or there is just too much that can’t be cut down, then use cross-reference links to take you around the document without manual scrolling. Also, a “Back to Table of Contents” link at the end of every section allows the reader to navigate back easily after jumping around.
3. Make It Easy to Read
“Pushing buttons should be easy, so why am I making so many mistakes? No one else seems to be having as much trouble as me.”
That’s the last thing you want to make someone feel. Nothing halts progress like making people feel stupid, because it triggers the most shameful stigma and injures their pride, and then they shut down. It makes us feel like something is our fault when it isn’t. After all, our brains aren’t computers; they’re not meant to be hooked up and run like a calculator nonstop for eight hours at a time. Even dairy cows are only milked two or three times a day.
Making instructions easy to follow is not optional or extra; it’s the entire difference between being useful and useless.
Pictures and screenshots. If you want someone to click a button, don’t write them a sonnet describing the button. Just insert a screenshot with the correct button circled and an arrow pointing to it. If you want someone to fill in a form or template, insert a screenshot that has an example of the information filled out. Don’t be shy; you’re not writing to royalty, so it’s more important to be literal and clear than official-looking.
Often, there are random buttons or fields that are obsolete or irrelevant, or idiosyncrasies about formatting and abbreviations, but the person giving instructions has already taken these details for granted and doesn't realize that a new joiner wouldn’t know. All of this stress can be extinguished in one fell swoop by giving an example screenshot of what to do.
Make everything shorter. This one is as easy to say as it’s difficult to do. For obvious reasons, make shorter paragraphs, shorter sentences, shorter words — bullet point lists, if you can.
Wherever there’s a comma, see if you can start a new sentence. Wherever you’ve used jargon, see if you can replace it with a plain English word. Look at your work product from the point of view of a normal person, not an 1800s judge: is it nice to look at and read? Or is it a pain in the ass?
Variation maintains interest. Especially if you can’t figure out how to shorten something, then juxtapose it with visual items that look different.
Long paragraphs can be surrounded by shorter paragraphs, pictures, or bulleted lists.
Short, abrupt sentences can emphasize a message and make it memorable.
The first word and last word of a paragraph are the most visible, so choose carefully to make them count; this might be an appropriate place to break a grammar or syntax rule.
An introduction or conclusion sentence can be separated into its own line for visual variation and emphasis.
There should be a logic to your color-coding, highlighting, and emphasis. When adding visual emphasis, the purpose is to draw attention to what’s most important and make a document easier to look at. But if one part of the page is highlighted, another bolded, and a third underlined, then the impact is diluted. If everything is drawing your eye equally, where should the focus be?
It’s okay to add emphasis, but create a clear hierarchy of what’s important. For example, bold and underline the most important parts, and then just underline the secondary parts. That way, the eye knows where to go first, second, and then to the rest of the page. For another example, highlighting just one thing singles it out as the most crucial, key piece of information, which is a powerful move.
But as long as there’s an obvious logic, you can bold, underline, and highlight to your heart’s content.
Spell things out at least once. Everybody has an acronym that they’ve used for years and don’t know what it actually stands for, and that’s okay. Industry acronyms are out of control and it’s the spirit that counts. However, just to satisfy curiosity and instill a little extra confidence, spell out each acronym (in parentheses) the first time you use it, unless it’s truly common knowledge. Someone will thank you!
Bonus Points: Proofread and Ask, “What Is The Purpose?”
What is the purpose of this sentence? What is the purpose of this word? Go line by line, as much as you have time for. Delete or revise anything that doesn’t have a good answer.
Where, in this document, do I communicate this or that message that I wanted to get across? If you can point to each section of your document that answers these questions, success!
If all goes well, this is what we’ve accomplished: Effectively teach someone else how to do something and give them the confidence and motivation to do it autonomously with minimal room for human error and stress. As far as a day’s work goes, it’s not a bad outcome, and certainly nothing to be ashamed of.
P.S. Read the rest of the Knowledge Management Series here:
Part 1: Your Secret Weapon of Knowledge Management