6 ms·

He's not exposited it well, but he's saying the documentation of the libraries is more important than the libraries themselves [middle, 4th paragraph]. It's an

by 10ren 17y ago

He's not exposited it well, but he's saying the documentation of the libraries is more important than the libraries themselves [middle, 4th paragraph]. It's an interesting point, like saying that advertising of a product is more important than the product itself. Sounds ridiculous, doesn't it? But if you don't know about the product, or what it can do, or how it can be used - it is of 0 use to you. It might as well not exist. No matter how great it is nor how much its creators know about it...

pavlov 17y ago
Personally I find that the sample code is often the most important part of the library. I like to learn by doing, and rewriting sample code into my own style is a great way to do that. It needs to be supported by high-quality documentation, of course - preferably there should be a walkthrough of the code with relevant documentation links that go into more detail to explain the thinking behind the library. What I really hate is documentation that's obviously written by technical writers who understand the concepts in the abstract, but have never written any code using it. It's frustrating to wade through pages and pages of patronizing explanations when a real-world example would do the job so much better. (The worst example of this documentation genre I've ever seen is probably Symbian's C++ API documentation. First they spend an eternity justifying their pseudo-Hungarian type naming convention. Then they introduce a class hierarchy of a dozen classes for basic buffers and strings, dither over all the irrelevant details of the implementation, and claim that it's an "elegant example of object-oriented design". I guess they expect their audience to be of the captive kind that is forced to sit in a class room for a few weeks listening to trivialities, so it makes sense to waste all that time going over outdated '90s buzzwords.)
- aaronblohowiak 17y ago
  Good documentation includes examples. That's why `man` pages have an EXAMPLES section. The point you seem to be making about documentation organization being driven practically instead of horn-tooting, I completely agree with.
  - pavlov 17y ago
    Sorry if my point was so unclear. I agree completely that examples are an integral part of documentation. But it sometimes seems that this point is lost on the programmers and tech writers who should be collaborating to produce the documentation (or perhaps management is to blame for treating these roles too separately). The result is often documentation that's too verbose, too rigidly structured according to the implementation's hierarchies and doesn't match the thought processes and expectations of the target users.
    - aaronblohowiak 17y ago
      Right, and I was similarly unclear. I think that examples should be interwoven with the documentation, and I think that your insights into the systematic reasons for this are spot-on.
  - stonemetal 17y ago
    >>Good documentation includes examples. Should be: Good documentation includes good examples. Most example code out there is the worst code I have ever seen. Typically it looks like something someone slapped together in 5 min. Removing error handling to "improve clarity" just means that there are no examples of what errors the author of the library actually thinks are important or how to recover from recoverable errors.
- DougWebb 17y ago
  I agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can produce automatically from a codebase that does not contain lots of hints and extra documentation. A listing of classes and their methods is not even an adequate reference guide, let alone an adequate explanation of how to use the library and why it was written the way it was. As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.
  - eru 17y ago
    The Perl module documentation seems to be modelled on man pages.
    - DougWebb 17y ago
      Yep. And sometimes Perl module documentation can be as bad as man pages can be. Good guidelines for how to document are not sufficient; good technical documentation skills are necessary as well.
hxa7241 17y ago
It is not an interesting point. It is merely a literary 'trick'. It is just unconscious use of the rhetorical form 'paradox': it says something apparently nonsensical in order to capture attention, perhaps to express a related truth. The way to handle rhetoric is to recognise it and not be diverted by it, and look if anything substantial is actually being said. I am not saying it is delibarate, and deceptive; it is more like a cliche -- it can happen accidently in writing something. Saying "documentation is more important than library" really is nonsense. If you had one but not the other, which would you choose? If you have only the library, you can probably figure out how to use some parts. If you have only docs, you have nothing working at all. The point of course is: documentation is important. Almost certainly very true. Though it now seems rather mundane. The best treatment for such a situation is not to follow some rhetorical flow, but to search for something more interesting to say. Or just say it simply, express a little enjoyment maybe, and have a brief blog post.
- WrongBot 17y ago
  Documentation is more important than the library, in terms of quality. Obviously you need the one before you can have the other, but I'd take a slow and slightly buggy library that I know how to use over a more functional one that I'll never figure out.

by 10ren 17y ago

pavlov 17y ago

Personally I find that the sample code is often the most important part of the library. I like to learn by doing, and rewriting sample code into my own style is a great way to do that. It needs to be supported by high-quality documentation, of course - preferably there should be a walkthrough of the code with relevant documentation links that go into more detail to explain the thinking behind the library. What I really hate is documentation that's obviously written by technical writers who understand the concepts in the abstract, but have never written any code using it. It's frustrating to wade through pages and pages of patronizing explanations when a real-world example would do the job so much better. (The worst example of this documentation genre I've ever seen is probably Symbian's C++ API documentation. First they spend an eternity justifying their pseudo-Hungarian type naming convention. Then they introduce a class hierarchy of a dozen classes for basic buffers and strings, dither over all the irrelevant details of the implementation, and claim that it's an "elegant example of object-oriented design". I guess they expect their audience to be of the captive kind that is forced to sit in a class room for a few weeks listening to trivialities, so it makes sense to waste all that time going over outdated '90s buzzwords.)

aaronblohowiak 17y ago
Good documentation includes examples. That's why `man` pages have an EXAMPLES section. The point you seem to be making about documentation organization being driven practically instead of horn-tooting, I completely agree with.
- pavlov 17y ago
  Sorry if my point was so unclear. I agree completely that examples are an integral part of documentation. But it sometimes seems that this point is lost on the programmers and tech writers who should be collaborating to produce the documentation (or perhaps management is to blame for treating these roles too separately). The result is often documentation that's too verbose, too rigidly structured according to the implementation's hierarchies and doesn't match the thought processes and expectations of the target users.
  - aaronblohowiak 17y ago
    Right, and I was similarly unclear. I think that examples should be interwoven with the documentation, and I think that your insights into the systematic reasons for this are spot-on.
- stonemetal 17y ago
  >>Good documentation includes examples. Should be: Good documentation includes good examples. Most example code out there is the worst code I have ever seen. Typically it looks like something someone slapped together in 5 min. Removing error handling to "improve clarity" just means that there are no examples of what errors the author of the library actually thinks are important or how to recover from recoverable errors.
DougWebb 17y ago
I agree completely, and this is what I _dislike_ the most about Java libraries. Far too much Java code that I've seen has relied entirely on what Javadoc can produce automatically from a codebase that does not contain lots of hints and extra documentation. A listing of classes and their methods is not even an adequate reference guide, let alone an adequate explanation of how to use the library and why it was written the way it was. As a counter example, I find that most perldoc documentation on CPAN is pretty good, because the standard practice for Perl module documentation is centered on the documentation sections that should be included _other than the list of methods_. NAME, SYNOPSIS, DESCRIPTION, USAGE, AUTHOR, SEE ALSO are all standard sections, and the kind of stuff that javadoc normally generates is just a subset of USAGE.
- eru 17y ago
  The Perl module documentation seems to be modelled on man pages.
  - DougWebb 17y ago
    Yep. And sometimes Perl module documentation can be as bad as man pages can be. Good guidelines for how to document are not sufficient; good technical documentation skills are necessary as well.

hxa7241 17y ago

It is not an interesting point. It is merely a literary 'trick'. It is just unconscious use of the rhetorical form 'paradox': it says something apparently nonsensical in order to capture attention, perhaps to express a related truth. The way to handle rhetoric is to recognise it and not be diverted by it, and look if anything substantial is actually being said. I am not saying it is delibarate, and deceptive; it is more like a cliche -- it can happen accidently in writing something. Saying "documentation is more important than library" really is nonsense. If you had one but not the other, which would you choose? If you have only the library, you can probably figure out how to use some parts. If you have only docs, you have nothing working at all. The point of course is: documentation is important. Almost certainly very true. Though it now seems rather mundane. The best treatment for such a situation is not to follow some rhetorical flow, but to search for something more interesting to say. Or just say it simply, express a little enjoyment maybe, and have a brief blog post.

WrongBot 17y ago
Documentation is more important than the library, in terms of quality. Obviously you need the one before you can have the other, but I'd take a slow and slightly buggy library that I know how to use over a more functional one that I'll never figure out.