Adobe DITA World

Get new posts delivered straight to your inbox.

Subscriber count: 4,039

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe FrameMaker

Following instructions involves learning a new language -- adventures with Tinker Crate projects

Apr 13, 2017 • general

In following instructions to assemble a Tinker Crate project over the weekend, I realized that a list of parts (essential for assembly kits) is similar to a glossary in that it teaches you a new vocabulary. Software projects also involve new vocabulary terms, but software instructions often omit the glossary (or list of parts). However, if you look at the glossary as a dictionary for new vocabulary, its inclusion in software instructions becomes just as essential as a list of parts in an assembly manual.

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.

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 4,039

About Tom Johnson

Tom Johnson

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.