Following instructions involves learning a new language -- adventures with Tinker Crate projects
Tinker Crate projects
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.
Where I got stuck
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.
List of parts = glossary
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.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.