4 ms·

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

by acqq 8y ago

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

dredmorbius 8y ago
That is the worst and most useless type of documentation. Also the most common.
- 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 ago
    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#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 ago
    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.
nerdponx 8y ago
Don't forget that getSize(-1) looks up the default frob. Which they use liberally in the code but never document.
wpietri 8y ago
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.
tomcam 8y ago
// Increment frob frob++;

by acqq 8y ago

dredmorbius 8y ago

That is the worst and most useless type of documentation. Also the most common.

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 ago
  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#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 ago
  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.

nerdponx 8y ago

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

wpietri 8y ago

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.

tomcam 8y ago

// Increment frob frob++;