This past weekend, as most people do in their free time, I put together some stuff by following someone’s instructions. My wife ordered Tinker Crate kits for our kids. Tinker Crates are little science kits in a box that require you to follow instructions to make some cool little model, contraption, or other gizmo. In this case, I helped my 6-year-old build an infinity mirror.
(There are actually many more parts than shown here.)
Here’s an online video that shows the construction process:
(I didn’t discover this video until writing this post — it actually would have been really helpful.)
This Tinker Crate project was beyond my 6-year-old’s ability to follow the instructions, so it was mostly me assembling the project and having my 6-year-old stick adhesives on certain objects, uncovering sticky backings and placing little objects where they should go.
You probably assembled something this past weekend as well (from some store). My 16-year-old daughter also spent the afternoon assembling a new desk from IKEA in her bedroom — a task I was more than happy to leave entirely up to her to complete, from start to end.
While I was assembling the infinity mirror, I got stuck on a certain step. (Don’t we all get stuck on some step or another in following instructions?) The instructions said to put the small silver circles onto the little circular adhesives. The only thing is, what “small silver circles”? How small is small? The size of a dime? The size of a silver dollar? I wasn’t sure. I seemed to have multiple sizes of silver cardboard circles.
Finally, I figured it out, but not before feeling entirely stumped for a good 5 minutes and watching some NBA basketball in the downtime.
I asked my older daughter if she got stuck anywhere in putting together her IKEA desk. Not really, she said. She said she had some leftover pieces and wasn’t sure if she’d missed something or if they were extras.
As you’re now expecting, I did realize a few things in putting together my little infinity mirror project. Almost without fail, every assembly manual that accompanies a physical product starts by listing all the parts in the package.
It’s not so important to know that you have all the parts. No, what’s important here is to understand the names of all of the parts.
This list of parts is really a dictionary that assigns names to the parts you’ll be working with. Imagine if you had to assemble something without having this list of parts and their names. Here’s a sample “dictionary” for working with a Tinker Crate project:
When you go to a step that might say, “Place the jellyfish decorations on the jellyfish felt piece,” or “Place the doohicky on the thingamajiggle,” or “Take the left hexapiece and insert it into the square knobkin,” or whatever, without a map/dictionary correlating objects with names, you would have to guess what each name referred to.
Even with IKEA’s wordless manuals, they still name their parts with 2x, 3x, and so forth names.
I think we will all admit that assembly instructions must provide a list of parts along with their names. And we assume that the writer will use these names consistently throughout the instructions. Following instructions is mostly a matter of learning new vocabulary and doing things with that new vocabulary. (Following instructions requires you to learn a new language.)
And yet, with software documentation, since we don’t ship a package of “stuff” with a bag of “parts” to users, we often think we can get away with not describing a list of terms that corresponds with the steps users will be performing.
All too often, software instructions often omit the “list of parts.” But in reality, we have our own list of special terms, and users will likely get stuck on some step where we tell them to do X, to configure the “thermacabobulator,” and the user will be thinking, WTF is a thermacabobulator?
Ultimately, the glossary is our list of parts. It’s the list of vocabulary the user will need to follow the instructions. If we look at the glossary just like that list of parts in assembly products, won’t be so casual in omitting it or in using terms not on the list.
In addition to providing a glossary prior to instructions, it’s also acceptable to define the terms along the way. In a step where you might say, “Now configure your thermacabobulator with the settings you want,” you can include a description of the thermacabobulator, or provide a tooltip or expandable text that describes it.
Get new posts delivered straight to your inbox.
I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.