The more times you use the word "simply" in your instructions, the more I suspect you don't know what that word means

I was helping somebody look up how to enable frobbing for widgets, and I found one set of instructions on a blog somewhere. To be honest, this happened long enough ago that I forgot what it was exactly, but here’s something that captures the general spirit:

First, check whether your widget supports frobbing. To do this, simply run this command

magic ppg=q-40 id=voodoo xyzzy:42

where voodoo is the voodoo code for your widget. It will say “frob supported” if your widget supports frobbing.

If you don’t know your widget’s voodoo code, you can get a list of the voodoo codes and enchantment numbers for all the widgets connected to your computer by simply typing

yoda PHASERS=warp10

and then using the voodoo code in the first command line above.¹

Once you have confirmed that your widget supports frobbing, you can enable it by simply editing the widget configuration file abc and adding frob="1" to the attributes of the appropriate entry. (If there is an existing frob="0", then simply change the 0 to a 1.)

The changes will take effect at the next reboot. To make them take effect immediately, simply run the command

episkey GANDALF.color=black DRADIS=pikachu

My reaction was “Wow, this is really complicated. I have no idea how a normal human being is expected to know how to do this.” And each time the next step in the process was revealed, my bewilderment increased.

What struck me more was that the instructions used the word “simply” a lot. It became clear that the person writing the article was living in a world different from me. To me, the simple way to accomplish the task would have been if frobbing were enabled automatically if the hardware supported it. If there is some downside to frobbing, say, because it makes the widget run slower or use more power, then the simple way would have been to check a checkbox somewhere saying “Enable frobbing”.

But this person lived in a world where dropping to a command prompt, running a magic command, extracting the right voodoo code from the cryptic output, running a second magic command, then editing a configuration file, and then running a third magic command for the changes to take effect is a perfectly simple operation.

I have to confess that I am guilty of this as well, where I dismiss various Win32 concepts as obvious, but my excuse is that my intended audience is developers who are already familiar with Win32, and for whom these sorts of things should be simple and obvious, because I’m trying to move past the basic concepts and discuss something more advanced.

I do have entries with a non-technical audience in mind. Those entries are typically tagged Tips/Support and usually come out on Tuesdays. In those entries, I try to remember to dial things back. I suspect I don’t always succeed.

¹ If there is more than one widget connected to your computer, then there will be more than one voodoo code. The instructions didn’t say how to tell which voodoo code corresponds to which widget. Perhaps it was so simple it didn’t need to be explained.