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.

Comments (49)
  1. Boris says:

    Raymond's awareness of Q40 in 2015 is highly instructive.

  2. Jon says:

    Knowing what to type isn't simple,  that's why instructions are needed.

    The physical act of typing "magic ppg=q-40 id=voodoo xyzzy:42" is simple - 34 keystrokes - compared to, for example,  explaining how to find and open a properties dialog box.

  3. Boris says:

    Jon: most people would copy/paste and cargo-cult it, so it wouldn't be 34 keystrokes.

    It also depends on the environment. While I was running Linux for about a year, I got fairly used to solving random issues in this manner. I expect better in OS X/Windows.

  4. Erik F says:

    @Jon: Cookbook-style instructions are fine, but they don't help when you're not sure if you should be using "xyzzy" or "plugh" because the documentation goes something like this: "NOTE: Use 'xyzzy' when checking a Widget-2.0 and 'plugh' when checking a Widget-1.0, except on the third Thursday of March, when you must use 'plover'." It goes without saying that nowhere in the documentation can you find out how to determine the difference between the different widgets. :-(

  5. Kevin says:

    @Erik F: Not to mention the useless error messages:

    > xyzzy

    Nothing happens.

  6. prprcupofcoffee says:

    Peter Norton's writing used to be festooned with statements to the effect that this-that-or-the-other-thing was "simplicity itself."

  7. Dave Bacher says:

    Are you sure that's from a blog and not from the Microsoft Knowledge Base?

    I think I saw these instructions last week on a Windows installer issue.

  8. Joe says:

    I had a quantum mechanics in college who told the class on the first day "the hardest thing for me to be a good prof for you all is that I have forgotten what it is like to not know this stuff"

    he wasn't a very good teacher.

  9. Erbo says:

    Boris: I'm pretty sure that's a Babylon 5 reference. (PPG = the handguns they used; Q-40 = Quantium-40, the ultra-rare element needed to make jumpgates work)

  10. Adam Rosenfield says:

    > (If there is an existing frob="0", then simply change the 0 to a 1.)

    That one I'd agree qualifies as simple (once you get to finding the config file, of course).

  11. Bob says:

    @Adam:

    > (If there is an existing frob="0", then simply change the 0 to a 1.)

    This can be an important note if the existing config file could be very long with the frob="0" embedded somewhere within it.

  12. not an anon says:

    @Bob:

    That's what Ctrl-F (or its equivalent in your editor of choice) is for...

  13. Yukkuri says:

    This sure reminds me of the world of open source software...

  14. Mark says:

    Someone had fun writing those fake instructions!  (I really like episkey, Gandolf.color=BLACK, and Pikachu all on one line.  I have no idea what dradis is, but I'm sure it's simple!)

  15. Jon Forrest says:

    Funny you should mention this. Philosophers love to say "clearly" in their papers. Same problem.

  16. Ken Hagan says:

    @Joe: Taking your professor at face value, at least he knew that this is a problem.

    @Boris: I was told the same story by a friend at uni, that he'd heard from someone else about their professor. Perhaps we're related...

  17. Nina says:

    As a tech writer, I try to avoid using "simply" in my instructions, no matter how simple the process seems to me. Because there's always someone out there who isn't going to find it simple at all.

  18. morlamweb says:

    @Adam, Bob, not an anon: sure, it's "simple" if you know that the file exists, can get to it for editing (permissions?), know what text to look for, and know the meaning of "frob=1" vs. other values.  Three easy steps or less!  It's simple only if you have in-depth knowledge of Widgets and frobbing.  If it really were as simple as the other blog author claims, then there would be no need for their blog post (or, at least, no need for those arcane command-line incantations)!

  19. morlamweb says:

    @Kemp: each operation is "simple" only if you already have knowledge of the command-line syntax for widget frobinators.  If you lack such knowledge, but you have to enable frobbing for your widget, then each step becomes quite a bit more complicated.  If you know about the command-line tools then you have a leg up on those people who don't, but you still need to come up with the magic sequence of parameters out of the tool's parameter soup.

    The whole procedure, and each step, is "simple" only if you're in-the-know; for the uninitiated, it may as well be voodoo!

  20. Steve says:

    The frequency of "simply" makes me think it's more of a tic than it's used intentionally to convey meaning.

  21. neminem says:

    That's silly - everything he said to do *is* simple. Knowing *why* you're supposed to do those things and what they accomplish isn't necessarily simple, but copy-pasting a string into a command line and hitting enter, or copy-pasting a line into a specified text file and hitting save, are both simple, and he didn't claim anything else?

  22. bzakharin says:

    My favorite professor in college told us a story about *his* professor who was so intimidating that nobody ever asked questions at his lectures: everything was trivial after all (our professor himself was only intimidating enough that people only asked intelligent questions). Once, to everyone's shock, someone raised a hand at one of his lectures to ask whether the result he arrived at was trivial. Without saying a word, the professor left the lecture hall and went to his office, only to come back one hour later (apparently no one left) and say "yes".

  23. Cesar says:

    The author used the word "simply" because each step was _trivial_. See catb.org/.../trivial.html definition 4 ;-)

  24. @Cesar: Each step was NOT trivial. Each step was wrought with hidden complexities and technicalities.

    Even if it was trivial, "simply" would have been outright redundant.

  25. cheong00 says:

    Oh, I didn't expect I'll ever see the word "pikachu" here. :P

    Btw, I can guess where it comes from. The original reply is simply "if you know the value, just edit the configuration files and reboot", the other instructions (discovery of settings and the step to make it work without reboot) are added later. I did this a lot.

  26. Kemp says:

    "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."

    He says that *each operation* is simple, not that the set of instructions all taken together is simple. And they are, in much the same way that any complex procedure can be broken into a series of simple operations. What you're asking for is that the entire procedure be converted into something simple (or, more accurately, that it be reduced to a single simple step rather than many simple steps).

    [I believe the article claimed that the entire process was simple, but to emphasize the point, it said that each individual step was also simple. -Raymond]
  27. Boris says:

    @Ken Hagan: I know, which is why I said it was highly instructive. The average SF viewer of today isn't likely to even know about Babylon 5, let alone remember an obscure fictional element such as Quantium 40. Unless, of course, Raymond was looking up shows and their terminology randomly online.

  28. Phill says:

    @Boris and @Ken I've heard several variants of that story over the years. The first one I heard attributed it so some famous mathematician during a conference presentation, but I can't remember the alleged person right now. Also worth noting that Richard Feynmann recounts a somewhat similar story about maths graduate students (in "Surely You're Joking, Mr Feynmann" IIRC) which would have been in the 1930s.

    I think it is just one of those anecdotes that gets reattributed to new people fairly regularly, and no-one knows whether it actually happens or was just a joke that got turned into a 'true story' anecdote.

  29. raphan says:

    @neminem - Except when copy&paste doesn't work because you are supposed to say PHASERS=stun and GANDALF.color=pink. And you don't have any idea why.

  30. Boris says:

    Executing command-line tools can be easier than looking up settings in nested dialog boxes, but sometimes there are unexpected failures. What if yoda is a common administrative tool which runs on the platform-independent Yaddle+ framework? What if the pikachu flag has been made obsolete? Suddenly you have to stop and think about what you're doing, and maybe you'll decide to shell out $10 for commercial software which does the same as this set of free utilities.

  31. Engywuck says:

    I've been told that one of the dumbest things a teacher can ask is "who can answer this simple question?". Students who know the answer don't think it worth their time, because it's simple and maybe the teacher will remember that they "only" answered simple questions -- and the students who can't answer feel dumb. Additionally sometimes questions the teacher thinks "simple" (in the given context) have hidden depths which good students see but are confounded because of the word "simple".

  32. Jason T. Miller says:

    >  I have no idea what dradis is, but I'm sure it's simple!

    Maybe so; it's the Battlestar Galactica radar analogue.

    Back on topic, this sort of thing is by no means restricted to the command line: graphical — to use the term loosely — programs that "helpfully" provide separate edit controls for each of their dozens of fiddly little options (and inevitably no means to save option sets for future use, because "simplicity") are far worse. As as a means of both automation and documentation, I'll take textual usage prompts and batch files over screen shots* and keystroke macros** any day. And there's nothing more tedious than step-by-step documentation with page after page of

       n. In the "Foo" box, enter "Ennyn Durin aran Moria" (without the quotes).

       n + 1. In the "Bar" box, enter "XLII" (again, without the quotes).

    and so on, in comparison to which "enter this command:" is the soul of wit.

    * If the distinction between a capital "I" and a lower-case "L" is important, so is font selection in your documentation, and, by extension, your UI, if text appearing only in screen shots forms an essential component of said documentation. In contrast, even the most poorly-thought-out usage prompts and man pages at least leave open the option to copy and paste.

    ** I've actually seen dialog boxes "designed" with an intentionally byzantine tab order to allow for sensible visual option grouping without breaking keystroke macro compatibility with previous versions where the same controls were organized haphazardly.

  33. Neil says:

    This reminds me of the time I wanted to write a batch file to eject a tape on a Windows 2000 server. I think it turned out to be easier to grant permission to a user to eject the tape remotely using a custom .mmc file referencing the Removable Storage Management snap-in.

  34. ch says:

    The cause of this is that there are two different meanings to the word 'simply'. (See http://www.oxforddictionaries.com/.../simply ). The sense in which it is used is where "simply X" means that it is sufficient to do X - not that X is simple, or even that doing X is simple. However, such use (especially when so extensive) is pointless, since the reader would already expect that the instructions would be sufficient, so there is no need to keep emphasising that they are. It suggests that either the author is accustomed to producing incomplete instructions or that the author's usual audience is accustomed to incomplete instructions and, either way, that the author is particularly pleased to be doing a better job this time.

    [Thanks for capturing this. That was another thing that bothered me, but I couldn't articulate it. Each time the article says "simply", I think that's the final step. And then it keeps on going... -Raymond]
  35. Cesar says:

    @Fleet Command: did you read the link I posted? The whole joke is that their definition of "trivial" is "I already know how to do it, so it's uninteresting".

  36. DWalker says:

    As some commenters have mentioned, whether something is "simple" depends a great deal on whether you have done it before, or not.  

    I find it simple to add a disk drive to, or replace a video card in, a computer, or to replace the CPU, or to reinstall Windows on a solid-state drive and re-activate.  Each of those things combines mucking around with computer hardware plus maybe doing some software stuff.  It's easy for me just because I have done it so many times.  I wouldn't make the mistake of telling someone else that these are "simple" if they haven't done it before, even though some things (like adding memory) do seem simple to me (once you have bought the right kind of memory).

  37. @Cesar: I did follow the link. I perceived no jokes. I still don't; writing well is my job and one that I take seriously.

  38. Ben Hutchings says:

    Similarly, "just" is a weasel word introducing a procedure more complex than it ought to be.

  39. voo says:

    @Fleet Command: Despite contrary opinions, it is generally accepted that writing well and having a sense of humour are not contradictory.

  40. Random832 says:

    Well when you have the command already in front of you, it is simple. Just copy and paste.

    Remember, the easy part is making the chalk mark. The hard part is knowing where to make it.

  41. imho says:

    For the writer, each 'simply' means you're one step closer to being done with this boring task of writing instructions. Except it's not boring, because each step has an 'easy' reward.

  42. Steve D says:

    @Random832

        "Remember, the easy part is making the chalk mark. The hard part is knowing where to make it."

    I can only add: of intermediate difficulty is ensuring those who need to know can locate your chalk mark when they need to later on.

  43. Mihai says:

    And this is why a certain OS will not "take over the desktop" unless this mentality goes away.

    Not believing that this is simple, but believing that this is normal and acceptable.

    Yes, you can see it on Windows / Mac OS X at times, but usually in documents for "techies".

    In "the other OS" you have to do this for day to day stuff (like pluging a cell phone in a USB port and expecting to access some files).

  44. Mihai says:

    BTW intimidating teachers, this is one that I have witnessed personally (university time).

    The math teacher presented a theorem (don't remember which one), but had three sub-points to prove.

    He glossed over the demonstration with: "the first point is obvious, the second one is trivial, and the third one results from the first two"

    The only one who dared challenge that was a colleague who was an European finalist in both Math and Physics Olympiads.

    "Sorry, but the first does not look that obvious"

    The teacher turns to the blackboard, and starts demonstrating it.

    After a long while, and 6 blackboards filled with small writing (about 10 square meters), he finishes the demonstration.

    Turns to the class and says "you are right, it was not obvious"

  45. Mark says:

    Jon: fewer keypresses to achieve something doesn't necessarily make it easier. It often makes it more fraught, as you're more likely to mistype and perform a different, unexpectedly valid operation. Just ask anyone who's started using vim.

    "episkey GANDALF.color=black DRADIS=pikachu"

    This reminds me of the "simple" git setup commands, which usually include things like git config --global color.ui=auto (to enable the default behaviour almost everyome wants).

  46. Skyborne says:

    I've used some 'simple' software.  The manual had detailed lists of instructions on performing Operation X, but would never tell you *why* you might want to perform Operation X.  Nor, if you wanted to do Task N, would there be any info on what operations make up that task.

    Kind of like reading per-method doc comments and being expected to divine whole-program organization, or even how to assemble calls to the class into a useful order.

  47. stefancaunter says:

    There is a problem with describing something inaccurately, but you are basically describing something that was analyzed 50 years ago by linguists. The language in recipes is different. Nowhere else do people tolerate being told what to do directly, without justifications or polite requests appropriate to the culture. Cookbooks order you around. Some of them say, "stir the pot", some say "give the pot a stir", some say "just stir that for a few minutes". Depends on the context.

    Is it simple to stir a pot? Not if you are a ten year old girl doing it for the first time. You don't have strength, coordination, knowledge of the tools, or understanding of what "stirring" should do. It is simple, however, if you are a 50 year old man who has been cooking for people for decades.

    So, you are observing that decontextualizing instructions reveals imperfect description of the actions required.

    Fair enough.

  48. kog999 says:

    I recently had to install some software that come in 3 different downloadable zip files. the instructions said extract file 1 to a folder. extract file 2 and 3 to the same folder so that you have 1 big folder with all the files unzipped. seems simple and it is but what would have been even simpler would have been if they just gave me 1 downloadable zip with all the files pre combined.

Comments are closed.

Skip to main content