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

Raymond Chen

Raymond

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.

Raymond Chen
Raymond Chen

Follow Raymond