Hacker News Reader

Comment by userbinator | Hacker News Reader

Compare the IBM PC/AT "Guide to Operations" of the same time:

http://www.minuszerodegrees.net/manuals/IBM_5170_Guide_to_Op...

No colour, and of course a CLI doesn't need a lesson in how the UI works, but plenty of technical information.

"The scroll lock light comes on when you press the Scroll Lock key or when your program is in the scroll lock mode. The scroll lock light goes off when you press the Scroll lock again, or your program is no longer in the scroll lock mode."

"The System (Sys) key has its functions defined in your operating system or application program manual."

Heh, it's like it's written by my co-workers that simply can't do anything user friendly but like to make totally redundant "documentation." E.g.:

"The option --result-dir specifies the result directory"

"The function int getSize( int frob ) returns the size of the frob. The parameter is frob." (God forbid they inform you what the allowable range of input or output is, in which units they measure the size or what the frob in their program means or what is actually measured or counted, and they never include an example of using anything)."

I hate this kind of documentation so much. The kind I hate the very most is the application manual that is constructed by dumping out the menu tree and then have somebody write something about every menu function. 85% of the prose being what any idiot could guess from the words clicked on to get there.

My plea to everybody: user-test your documentation. Give the thing to a novice, have them do tasks, see if they can figure it out. If nobody looks at the docs, great, just throw them out. But if they do look, make sure it is useful to the person who is looking.

Don't forget that getSize(-1) looks up the default frob. Which they use liberally in the code but never document.

That is the worst and most useless type of documentation.

Also the most common.

I suspect the problem is often that engineers try their best to write objective documentation and it unconsciously goes to an absurd extreme — “I shouldn’t presume to tell them how they might want to use this function, let’s just stick to the facts.”

(Btw this is an illustrative example of why you can’t have “news that just states the facts.” That principle doesn’t even work for technical documentation! You need some degree of interpretation and empathy for writing to make sense.)

My suspicion is that it's documentation written by people who don't use, don't know how to use, and do not understand the product.

Fundamentally, technology is means and method, and both point to ends or goal.

Technology is the study of means. (John Stuart Mill's definition. He also gives science as "the study of causes".)

Which means that documentation should point you at what you might want to do and how the tool(s) available to you serve that end. Referencing only the internal state of the system itself (and worse, at the most trivial level, as in the example give, which is by no means unusual in the field) is ... perfectly useless.

It's actually worse than useless, because you've got to wade through so much goddamned mud soup trying to find information that's actually useful. I've long had this problem with various "documentation by the pound" publishers -- Que and "Learn Foo in 24 hours" type series -- where the books are so padded with cute comments and junk statements that you cannot find the real meat.

O'Reilly's "Nutshell" series often go too far in the other direction, but at least the information is (usually) there.

The O'Reilly UNIX Power Tools book, a cookbook of recipes and methods with specific ends and goals explicitly stated is, pound for pound, probably the most valuable reference book I've ever bought. It doesn't cover everything (though it touches on a lot of material), but it covers a vast range of useful information and best of all gives you the tools to find out more.

You nailed it. Not only the lack of "empathy", they somehow even detest the users of the stuff they produce. I never understood that attitude, but I see it on the web in some forums or similar too. Like when somebody asks "how to convert picture from x to y given z" and some smart-* posts the link to the following instead of giving any useful example:

https://imagemagick.org/script/command-line-options.php#adap...

Where the option is "explained" as:

"The -adaptive-resize option defaults to data-dependent triangulation. Use the -filter to choose a different resampling algorithm. Offsets, if present in the geometry string, are ignored, and the -gravity option has no effect."

I bet they feel so smart every time they do that, when they give at the same time the technically correct and practically unusable answer (for anybody but the author of the program and two other friends of him). In my case they would reply, unsurprisingly, "see the documentation of getSize." And there would be of course also long getSize( long trunnion, int length )" and some 10 more.

Come to think about it, I've had a discussion here on HN just some days ago where some "programmers" stated that if I want to use a single click with the mouse on the scrollbar to get to the previous page:

- I should use PgUp and PgDown on the keyboard, har, har.

- is completely unnecessary in the time of wheels and touchpads

- that that means a PgDown button on the mouse is missing

- that I should remap the third mouse button (why should I need both Up and Down movement anyway?)

- Or a mouse gesture? FoxyGestures, a Firefox addon

- that what I wish is illogical and trying to use it so is being stubborn.

Anything but a single click. That worked before.

BTW Gnome is actively removing things that worked with such an attitude (trying to remove even the settings which allow the users to switch back to the saner behavior). Yay user friendliness. And when you check what they are doing themselves, they don't even use GUI, but live in the console the whole day. And to see the previous page in their terminal they press Control-PgUp (or was it Shift-PgUp) and believe that that is the most natural thing ever, needing both hands for such a task. But "they don't need it anyway."

Btw, I've spent enough time explaining "normal users" how to do "normal actions" that I really appreciate that the original Mac had a single button mouse:

You can explain it with "just click there" not every time with "click with the link button, no, click with the right button" etc.

  // Increment frob
  frob++;

And compare that to the corresponding IBM PCjr "Guide to Operations",

ftp://ftp.oldskool.org/pub/misc/Hardware/IBM/IBM%20PCjr%20Guide%20To%20Operations.pdf

which combines the conventional IBM-style step-by-step troubleshooting guide with an extensive keyboard tutorial featuring full-color, cartoon-style artwork on nearly every page, illustrating...the fact that someone at IBM thought a bland and largely uninteresting tutorial could be made more approachable by adding full-color, cartoon-style artwork to nearly every page.

That, or else there's some connection I'm missing between the Ctrl key, say, and towing childhood pets around in an improbably stable two-wheeled trailer behind one's tricycle...

It's striking to see that there is a full section of Troubleshooting and test procedures, over 250 pages for the PC manual, as if it was supposed to fail by default.

Apple did the opposite, user-centered approach meaning it should work by default.

Opposite cultures, indeed.

Apple's approach is "send it back to us if something is wrong", and more recently, "buy a new one".

The solutions in the test segment are all "note the error and have your system unit serviced", so there's no difference there.

Reply on news.ycombinator.com