News for hackers. Stuff that matters.
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.

There are no comments on this comment yet.