From: Charles Comstock Date: 2004-02-09T06:21:25+09:00 Subject: Re: Documentation approaches Gavin Sinclair wrote: >>[...] > > >>We definitely more complete docs on lots of things though, that is my >>main problem with Ruby. There are lots of things I know I can do, >>without duplicating work, but since I can't find docs on it, it's >>difficult to do. The push for RDoc is great, but I still have the same >>complaints about it that I have of Javadoc, it generally doesn't give >>some sort of example for each function, class in the library. I learn >>far more from an example of code use that encompasses a wide part of the >> library then a list of functions I can call in the library. The 2nd is >> great, but it only works if you know how to use it already. Fix the >>documentation and I think ruby will certainly spring ahead. > > > I fully agree on all counts. I'll just mention, though, that RDoc > actually encourages introductory/usage/example documentation, *so long as > the developer wants to write it*. For example: > I wasn't really trying to criticise RDoc or even Javadoc as a method of documentation, I was trying to point out that they are oft misused. Many times the developer decides against writing examples, and instead just lightly explains each function. I think the problem with class/library documentation in RDoc or Javadoc style, is that it's harder when you first dive in to get a coherent picture of how the library interacts. And that's the key component to a library, knowing what it does and how to do it. Functions tell how to set and check state, and generally how to start things and whatnot but it doesn't describe the core philosophy of how the library works. It's often very difficult to determine that from documentation that focuses on each function/field, and not on the grand scope of the library. Unless each function/field shows a good example on how to use it in the total context of the library. It would be nice to have a tutorial in each library to get your feet wet, and while it's certainly there in some, it's missing in lots, or difficult to find. There are certainly excellent examples of documentation in this format which do a good job of describing exactly what I want above, but there are many examples where it feels like the documentation is a couple remarks strewn throughout the source. In that case I prolly will get more from reading the source then looking at the rdoc. Sorry, I certainly think it's great that we have what we have, but I still feel like we can go alot further. > * http://extensions.rubyforge.org/ > > The *first thing you see* (an important consideration for people looking > at an RDoc screen for the first time) is a description of the project, > installation, usage, technical information, links, etc. > > * http://www.ruby-doc.org/stdlib/libdoc/pathname/rdoc/index.html > > Here, the first thing you see is a brief description of the 'pathname' > Ruby standard library. It could use a one-paragraph description and usage > example to help the casual browser (person, not software) decide whether > they're interested. However, the most important thing is the prominent > "For documentation, see class Pathname [linked]", which contains intro, > examples, and a method catalogue. > That's the style I like, particularly if the method catalogue shows how each function is used in an example. > RDoc was certainly not a hinderance to creating decent documentation for > the 'pathname' library! Sorry didn't mean to say it was a hinderance, just that perhaps not all were as diligent in writing documentation for there libraries as they could be. They say a picture is worth a thousand words, well I say a nicely commented example that illustrates how the library is supposed to interact is worth the same as all the single function documentation that can be thrown at me. Many thanks to all who have documented, and also to all those who have written libraries, I guess I just get frustrated when I find a library that does what I need, but I don't know how to use it. Charlie