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 commandmagic ppg=q-40 id=voodoo xyzzy:42
voodoois the voodoo code for
It will say “frob supported” if your widget
If you don’t know your widget’s voodoo code,
you can get a list of the voodoo codes and
the widgets connected to your computer by simply typingyoda PHASERS=warp10
and then using the voodoo code in the first command
Once you have
confirmed that your widget supports frobbing,
you can enable it by simply editing the
widget configuration file
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 commandepiskey 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
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
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,
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
and usually come out on Tuesdays.
In those entries,
I try to remember to dial things back.
I suspect I don’t always succeed.
there is more than one widget connected to your
computer, then there will be more than one voodoo
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.