News for hackers. Stuff that matters.
Re:Thoughts on, and pictures of, the original Macintosh User... by userbinator on Sunday December 16, 2018 @02:04PM (#18694537)
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.

Re:Thoughts on, and pictures of, the original Macintosh User... by acqq on Sunday December 16, 2018 @03:11PM (#18694925)
"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)."

Re:Thoughts on, and pictures of, the original Macintosh User... by wpietri on Sunday December 16, 2018 @06:09PM (#18695827)
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.

Re:Thoughts on, and pictures of, the original Macintosh User... by nerdponx on Sunday December 16, 2018 @05:32PM (#18695669)
Don't forget that getSize(-1) looks up the default frob. Which they use liberally in the code but never document.
Re:Thoughts on, and pictures of, the original Macintosh User... by dredmorbius on Sunday December 16, 2018 @04:55PM (#18695505)
That is the worst and most useless type of documentation.

Also the most common.

Re:Thoughts on, and pictures of, the original Macintosh User... by pavlov on Sunday December 16, 2018 @05:26PM (#18695639)
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.)

Re:Thoughts on, and pictures of, the original Macintosh User... by dredmorbius on Monday December 17, 2018 @05:50AM (#18698156)
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.

Re:Thoughts on, and pictures of, the original Macintosh User... by acqq on Sunday December 16, 2018 @07:34PM (#18696139)
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.

Re:Thoughts on, and pictures of, the original Macintosh User... by tomcam on Sunday December 16, 2018 @08:06PM (#18696251)

  // Increment frob
  frob++;
Re:Thoughts on, and pictures of, the original Macintosh User... by jasomill on Sunday December 16, 2018 @09:52PM (#18696609)
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...

Re:Thoughts on, and pictures of, the original Macintosh User... by kerouanton on Sunday December 16, 2018 @07:48PM (#18696197)
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.

Re:Thoughts on, and pictures of, the original Macintosh User... by userbinator on Sunday December 16, 2018 @09:26PM (#18696523)
Apple's approach is "send it back to us if something is wrong", and more recently, "buy a new one".
Re:Thoughts on, and pictures of, the original Macintosh User... by kalleboo on Sunday December 16, 2018 @10:00PM (#18696637)
The solutions in the test segment are all "note the error and have your system unit serviced", so there's no difference there.