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