[Rails] (Online) documentation for 1.0

[Lee O'Mara]

Justin Forder wrote:

> If you take successful open-source Java frameworks (Struts, Spring, 
> Hibernate) as an example, each has a reference manual which is the 
> definitive source of information on what the framework can do for you, 
> and how to use it. The API documentation exists, and you have the option 
> of having the source as well if you wish, but in normal day-to-day use 
> you should not have to look at these.

I think you can see a hint of the division you're speaking of if you 
compare the docs for a class vs. the docs for method (especially the 
main classes: AR, AV, AC,..) There's a page or two giving you an 
overview of how to use the class, followed by (relatively limited, very 
specific) docs for each method.

> I'm a beginner with Rails, currently working through Four Days on Rails, 
> and it's interesting that every reference to further detail from that 
> tutorial is a reference to RDoc API documentation. There *is* good 
> reference-style documentation there, but it is constrained by being 
> subordinate to the namespace/class structure of the code, and it seems 
> to be intended as a starting point, rather than as a full reference.

I agree about the namespace/class structure being an awkward fit for 
those unfamiliar with the "lay of the land". I'm sure there's a more 
intuitive way to expose the same information in a more accessible manner.

> It's reasonable for the API documentation to assume that the reader can 
> continue to browse the documentation for individual methods... but which 
> of these express a contract with the framework user, vs. being internal 
> and subject to change at the whim of the framework developer?

While I'm sure changes are bound to occur(especially before 1.0), I'm 
not particularly concerned with the distinction you make.. Maybe I don't 
see any documented (public) methods that could change that a 
framework-user wouldn't like to know about?

> Sorry if this is rather inarticulate - I just know that some ways of 
> packaging documentation *do* work, and that I have had problems finding 
> the information I need for Rails.

I think it's a debate worth having. You're far from the first person to 
cite that issue.

--
  Lee