4 ms·
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 pres
by pavlov 8y ago
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.)
- acqq 8y agoYou 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#adaptive-resize 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.
- dredmorbius 8y agoMy 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.