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.