IKEA is known as a purveyor of build-it-yourself flatpack furniture. LEGO is known as a purveyor of build-it-yourself toys. Both are known for their instructions. The latter’s are considered incredibly clear and useful, while the former’s are often derided as arcane and confusing—though the major difference between the two is color printing.
These two companies are great examples of why instructions are important. Indeed, Sonya Vasquez has learned this lesson well, and came down to Supercon 2023 to tell us all about it. Prepare to learn all about how to write great step-by-step instructions that enable greatness and never frustrate the end user.
This, Then This, Then This
Before we discuss the talk, it’s important we acknowledge something. The audio on Sonya’s talk is completely absent until about seven minutes in. Perhaps we should have put better instructions on the streaming computer’s mixing desk or something. In any case, it doesn’t harm much—when the audio comes in, Sonya is already telling us about one of her early builds.
The talk starts by looking at a fun little project—Sonya’s GameCube-Bot. It’s a simple robot chassis that fits into the plastic case of a Nintendo GameCube, allowing it to be driven around on the floor like an RC car. The result was both remarkably cute and nicely maneuverable. Initial reactions were positive, and that got Sonya thinking. “How do I share this with people?” she says. The answer? A more accessible build method, and of course—instructions!
GameCube-Bot 2 was designed to rely on laser-cut plastic parts instead of expensive machined aluminium parts. “I can just put the design files on the internet, but actually, I think I need some sort of instructions,” said Sonya. Thus, she laid out the bill of materials, parts, and processes required to build one, and threw it all on Instructables.
“I learned a lot from this process,” she says. “I realized this is actually a lot of work.” The project taught Sonya multiple valuable lessons. She notes the value of quality photographs for illustrating a build process like this, which presents challenges around getting the right lighting, angles, and focus. That can be particularly difficult for complex mechanisms, especially where gravity might make it hard to keep parts in place. Then, if your design changes, you have to go back and do all the work again!
Sonya’s next big project was The Tentacle, which you might remember from her articles published here back in 2016! The animatronic appendage was designed in CAD, relying on a combination of off-the-shelf and laser-cut parts. Again, once the design was complete, she had to contemplate how to share this design with others. Once again, she didn’t just supply the design files themselves, but the build instructions too! Since it was all designed in CAD, she was able to reuse these models to create diagrams and animated GIFs for visual aids. This was, in many ways, easier than just relying on photographs alone. She later refined her instructions for a workshop at the Hackaday Supercon, teaching many people how to bring their own creepy tentacles to life.
The skills learned on these projects have served Sonya well in her later career. She next walks us through the Jubilee multi-capable CNC platform, which she developed at grad school. Along the way, we learn more great techniques for creating clear instructions, such as that color is always helpful, and that community feedback is very valuable. In fact, the size of the community for any given project is generally larger the better the instructions are. The less guesses and leaps of logic required by the end user, the broader your user base can be.
Ultimately, we’re taught that good instructions are about removing the need for thinking on the builder’s part. The person crafting proper instructions decides what the builder does and the order they should do it in. Good instructions are about allowing someone to reliably replicate a project. It’s also worth noting that build instructions don’t need to teach the builder about the design of the project—they should focus on its assembly.
On the practical side, Sonya notes that using your CAD software to manage your parts lists and BOM can be a big time saver—allowing for automatic updates of your instructions as your design changes. There’s also great value in creating 1:1-sized reference sheets that allow your builders to quickly identify parts unambiguously. Using subassemblies to break things down into more manageable chunks can also ease the burden on the builder.
Meanwhile, color diagrams can be a big boon, too—and Sonya explains the value of using real colors or false colors in different contexts where necessary. You might also want to explore using safe and inclusive color palettes that minimize issues for those with varying types of color-blindness using tools like Viz-Palette. Sonya also shares valuable insights into making wiring diagrams that are accurate and easy to read.
If you’ve ever worked on a project that you want other people to build, you could certainly learn a trick or two from this talk. Being able to craft quality instructions is a boon to your own work, and a blessing for anyone that tries to replicate it. Better documentation helps everyone, after all, and this talk is a great resource for anyone trying do produce just that.
I’m part of the R2-D2 build community, and almost across the board, the instructions that people write for assembling their designs (e.g. the feet) are shite. These are brilliant people in their designs, no doubt, but I see them on the build forums answering the same questions over and over again because the instructions are so unclear. Yes, I understand they would rather spend their time creating or improve designs, but they would also benefit from better instructions which reduce their time answering questions. Many of the instructions, if they exist at all, seem to be pages and pages of fully overwritten paragraphs. Fewer words, more photos and diagrams, please!
A classic example of skills not generally being generalizable. A very smart person can still be terrible at making other people smart. A great engineer can be bad at teaching others how to assemble the thing. Of course it would be better if he wasn’t.. But sometimes this job is best given to an assistant, and of course there is the question of job security through strategically poor documentation…
I do this for my projects at work. After getting a rough prototype going I figure out the general outline for building the real thing. I write some instructions, then I try to forget the details and rely only on what I have written. If I find that I’ve told myself to do something dumb, or in the wrong order, or if I’ve missed something out I revise the instructions and try again. I also follow the final instructions from end to end so that I have an order-of-magnitide estimate of how long it should take someone to assemble.
I am most proud of giving my latest project package to an intern and saw that they replicated the technique for their project. When they left we had full and complete documention.
I also do something similar for software development and write an outline of what the code should actually do in comments. Then I just code up each part. Iterate as needed. Code + documentation, done!
The main difference between Lego and Ikea assembly instructions is the audience. Lego toys are popular with children, who are used to being confronted with slightly frustrating tasks that they haven’t learned how to do perfectly yet, and a small subset of adults for whom this type of work is second nature. Ikea furniture, on the other hand, is for everyone: the non-AFOLs out there are much more vocal than those of us who can assemble a BILLY bookcase in their sleep. Ikea’s instructions are consistently good. In fact, you don’t appreciate how good their design and instructions are until you have to deal with (most of) non-Ikea flat-pack furniture.
I agree with Sonya in many ways. Good instructions are hard to make. They’re even harder to keep up to date. Tables are good, colour helps, and so on. I also learned that people handle assembly instructions very differently. Here’s an example: https://amberspyglass.co.uk/wiki/EShapeoko_1.4_Assembly:_X_Carriage . I had feedback from “clear images, didn’t even read text” to “drawings meh, text helpful and clear” to “diagrams and text incomprehensible, need video”. Personally, I can’t stand video instructions for straightforward stuff. Sure, if there’s a tricky step where you need three hands while holding something down with your chin, a brief video can help, but, other than that, give me diagrams and tables, plus text for steps that don’t illustrate well (“file down any burrs”), additional detail, warnings against common pitfalls, and so on.
As part of my job, I’ve written many work instructions for assembling devices for mass production. Lots of good stuff here. I’m definitely in the taking lots of pictures camp, since my employers have never wanted to pay for a license of Solidworks for me to use.
I’m frequently irritated on hackaday.io or (especially) instructables by cool projects that have garbage instructions for building it. Without better instructions, it’s basically just a show and tell of a project with some random pictures that show how to build a few things, but lack many details and context. Or worse, just showing a video. In my opinion, well thought out videos are a great supplement, but are an inferior way of documenting the entire build process without written build instructions.
My work instructions are the reference for how things should be made at the company I work for. Our assemblers are expected to follow my work instructions or face disciplinary action depending on the severity of the assembly defect. On the other hand, like one of the last things Sonya indicated in this video, build instructions should be “living” documents. If assemblers or production supervisors find issues with my work instructions, they are expected to notify me so I can evaluate it and possibly revise the instructions.
When creating a brand new work instruction, I always seek to get as much feedback as possible. I will usually include at least one other engineer, the Production Supervisor, and the Operations Manager. Different people think differently than I do, and they tend to catch issues that I accidentally overlooked. Reviewing documentation is not the most fun thing to do, so sometimes I need to harass, I mean follow up several times, with individuals who I want feedback from.