Spy Fox Some Assembly Required
Vickey Melling
I don't know anything about the Chinese company that made the device, but it strikes me that before retailers put products on their shelves, they ought to make sure that the assembly instructions actually work.
This is not an isolated experience. Much of what we buy these days requires some assembly and -- in many cases -- the out-of-box-experience is less than pleasant. Whether it's bookcases or barbecues, retailers shelves are stocked with products that require the consumers to be part of the manufacturing process. Once in awhile it's easy, but too often its stressful and it's not uncommon for the instructions to be inadequate or incomplete or lack anything other than pictures that are supposed to enlighten you as to what to do.
In my open source courses, I spend a lot of time working with new developers who are trying to make sense of issues on GitHub and figure out how to begin. When it comes to how people write their issues, I see all kinds of styles. Some people write for themselves, using issues like a TODO list: "I need to fix X and Y." Other people log notes from a call or meeting, relying on the collective memory of those who attended: "We agreed that so-and-so is going to do such-and-such." Still others write issues that come from outside the project, recording a bug or some other problem: "Here is what is happening to me..."
Because I'm getting ready to take another cohort of students into the wilds of GitHub, I've been thinking once more about ways to make this process better. Recently I spent a number of days assembling furniture from IKEA with my wife. Spending that much time with Allen keys got me thinking about what we could learn from IKEA's work to enable contribution from customers.
I am not a furniture maker. Not even close. While I own some power tools, most were gifts from my father, who actually knows how to wield them. I'm fearless when it comes to altering bits in a computer; but anything that puts holes in wood, metal, or concrete terrifies me. And yet, like so many other people around the world, I've "built" all kinds of furniture in our house--at least I've assembled it.
In case you haven't bought furniture from IKEA, they are famous for designing not only the furniture itself, but also the materials, packaging, and saving cost by offloading most of the assmbly to the customer. Each piece comes with instructions, showing the parts manifest, tools you'll need (often simple ones are included), and pictorial, step-wise instructions for assembling the piece.
IKEA's model is amazing: amazing that people will do it, amazing that it's doable at all by the general public! You're asking people to do a task that they a) probably have never done before; b) probably won't do again. Sometimes you'll buy 4 of some piece, a chair, and through repeated trial and error, get to the point where you can assemble it intuitively. But this isn't the normal use case. For the most part, we buy something we don't have, assemble it, and then we have it. This means that the process has to work during the initial attempt, without training. IKEA is keen that it work because they don't want you to return it, or worse, never come back again.
Last week I assembled all kinds of things for a few rooms in our basement: chairs, a couch, tables, etc. I spent hours looking at, and working my way through IKEA instructions. Take another look at the Billy instructions I included above. Here's some of what I notice:
It got me thinking about lessons we could learn when filing issues in open source projects. I realize that there isn't a perfect analogy between assmbling furniture and fixing a bug. IKEA mass produces the same bookshelf, chairs, and tables, and these instructions work on all of them. Meanwhile, a bug (hopefully) vanishes as soon as it's fixed. We can't put the same effort into our instructions for a one-off experience as we can for a mass produced one. However, in both cases, I would stress that the experience is similar for the person working through the "assembly," it's often their first time following these steps.
These steps aren't always possible or practical. But it takes less work than you might think, and the quality of the contributions you get as a result is worth the upfront investment. In reality, you'll likely end up having to it in reviews after the fact, when people get it wrong. Try doing it at the beginning.
Here's a fantastic example of how to do it well. I've tweeted about this in the past, but Devon Abbott's issue in the Lona repo is fantastic: Here we see many of the things outlined above. As a result of this initial work, one of my students was able to jump in.
I want to be careful to not assume that everyone has time to do all this when filing bugs. Not all projects are meant for external contributors (GitHub actually needs some kind of signal so that people know when to engage and when to avoid certain repos), and not all developers on GitHub are looking to mentor or work with new contributors. Regardless, I think we could all improve our issues if we thought back to these IKEA instructions from time to time. A lot of code fixes and regular maintenance tasks should really feel more like assembling furniture vs. hand carving a table leg. There's so much to do to keep all this code working, we are going to have to find ways to engage and involve new generations of developers who need a hand getting started.
Given this is 2021 I knew when FedEx delivered the box not by the door bell ringing but because of the dogs barking and what sounded like someone dropping a pallet of bricks in the driveway next to my kitchen door. By the time I got to the door the FedEx delivery vehicle was driving out of sight.
If you had told the crafters of fine furniture a century ago that their predecessors one day would sell chairs, tables, dressers, and such by boxing the pieces together, tossing in an Allen wrench with complementing screws, and providing confusing yet short instructions on how to assemble them in fine print in 72 different languages on a small piece of paper they would likely think you were delusional.
But if for some reason said pieces of metal and drilled holes are ever so off even just a smidgen of a smidgen that putting together such furniture as a solo act using just an Allen wrench and your hands can become an adventure.
For the record, the instructions estimated it should take 30 minutes to assemble both chairs. But then again the instructions said assembling them required no tools. The last time I checked Allen wrenches were considered tools.
Finally after not being able to get the chairs together I checked for the customer help line. It was a number accessible between 1 and 5 p.m., East Coast time Monday through Friday. Of course it was the weekend.
Senior Mixed Reality Software Architect, Mixed Reality & Windows Development MVP. Talks about Mixed/Augmented Reality Cross platform MR development, HoloLens 2, Magic Leap 2, Quest, Unity, .NET, Azure
The third thing you might want to have a very good look at. If you have used the default MRTK3 profile in Project Settings, everything you have selected will be selected correctly in the new profile. However, if you have created a custom profile - for instance, because you wanted to have the speech recognition subsystem enabled, or because there needed to be an additional subsystem, like the people at Magic Leap needed for their hand tracking, you might be in for a nasty surprise:
Some of the subsystems your profile pointed to have changed names, so now your profile points to systems that no longer exist (see warning at the top), while the subsystems that were selected in the pre-release versions are now no longer selected. This might lead to, for instance, hand tracking no longer working. The trick is to make a new, empty MRTK profile and add whatever you need back to it, or make a fresh copy of the MRTK3 profile and change the settings to what they were before the upgrade.
There is a fourth thing you need to check: prefabs or even scenes might have references to namespaces as well. For instance, suppose you have created a simple default cube while using a pre-release version of the MRTK3, added an ObjectManipulator to that, and turned that into a prefab - and then upgraded, you are in for a surprise. If you open that prefab in an editor - for instance, Visual Studio Code
The namespace issue, of course, is a logical side effect of the MRTK3 coming under the stewardship of an extended steering committee in which not only Microsoft has a seat at the table but also Qualcomm and Magic Leap, as announced by Robin Seiler, Corporate Vice President and Chief Operating Officer of the Windows + Devices organization, on August 21. However, this required quite a bit of work, with some challenging pitfalls. It may be related to the fact that I skipped the pre-18 version and went directly from pre-17 to GA. I initially attempted to upgrade to pre-18, as suggested on the HoloDevelopers Slack, but that did not work out. So, I started from scratch and this time I got to the other end.
c80f0f1006