From: Conor Hunt <conor.hunt+rails@...>
Date: 2006-06-02T03:53:24+09:00
Subject: Re: Ruby Manual

> I also strongly disagree with this kind of fragmentation - it's just not
> what we need. It may be my ignorance (Not up on rannotate yet) but I
> can't see why we need either, given that ruby-doc.org is strong, getting
> stronger, and has a wiki for comments and so forth. Surely it's best to

I can offer an opinion on why I think Rannotate helps improve things, 
but generally they all because Rannotate has put all of the 
documentation in a database (in a very flexible format)

1. Searching:
Rannotate can search at a very detailed level because everything is in 
the database. Try it out. The search can be also be very easily made 
more comprehensive.

2. Inline Annotations:
The annotations are inline with the documentation, you don't have to go 
to a separate page. You can see at a single class which methods have 
annotations.

3. Getting documentation back into the core:
Maintainers will be able to click on the documentation on the site, edit 
the RDoc (perhaps incorporating user comments) and then generate a diff 
that can be *directly* applied to the source code repository.

4. Multiple versions of libraries:
You can host multiple versions of a library. Perhaps some people are 
working with Ruby 1.8.4 and some with Ruby 1.8.3. It doesn't matter, 
Rannotate will store both versions of the library, let you view either, 
and can even show you the differences between the two. Check this out on 
the rails site. Shows you what changed between versions of Rails for a 
single class:
http://rails.outertrack.com/history/RaClass/ActionController::Base

5. CSS.
Easy to create user selectable themes for the site because everything is 
database driven.

--
Conor

-- 
Posted via http://www.ruby-forum.com/.