[Nitro] A Request for Help

[James Britt]

I run ruby-doc.org.  For over a year I've considering ways to to make it 
better, more usable, offer Web services, and make it self-sustaining. 
For any and all reasons you care to imagine, I'm nowhere near what I've 
wanted to accomplish.

I've made a few attempts are rewriting the site as a Nitro application, 
but it keeps getting sidetracked by mundane demands such as earning a 
living.

However, some of the recent work others have been doing with Og/Nitro 
suggest that the essential pieces have are already around in some form 
or another, if not actually available to be dropped into place.

I'm asking for help from the Og/Nitro community to rewrite ruby-doc.org.

I believe this be very helpful not just to me, but the Ruby community at 
large, and Nitro development and developers in particular.

I've talked to a few people who have been interested in working with 
Nitro, but who told me that the lack of documentation and good, 
real-world examples to study makes it a bit hard.

I started on "Nitro: Step-by-Step" as a way to teach myself Nitro, but 
even that would is intended as a basic introduction.  A solid, 
reasonably  complex application, with all source code freely available, 
would be a boon to Og/Nitro exposure.  Documentation on the design and 
development techniques would be a big help, too.

My plans for ruby-doc.org were mostly focused on changing two sections. 
  The site has had a blog-ish main page where I add announcements of new 
and interesting Ruby documentation.  Early on, this was a trivial task, 
as the amount of new resource was slim.  But this has changes, and 
people are pushing out blogs, wikis, how-tos, and tutorials left and right.

I've simply gotten too busy and too tired of the tedium to keep up.  I 
started investigating ways to exploit existing resource tracking and 
classification tools, such as del.icio.us.   I assembled a prototype app 
that would snarf Ruby-related items from del.icio.us RSS feeds and stash 
the posts and tags into a local database.  A Web UI then allowed for 
faceted/tagged navigation of these resources.  It mostly worked, though 
I may have been too ambitious in my plans for providing high-level 
auto-categorization.  I still like the basic idea, but think sticking to 
a  navigation scheme similar to what del.icio.us uses, or some 
community-based resource submission schemes, such as used by digg.com, 
might be better.  But, whatever the scheme, I think it would make for an 
interesting Og application.

The other main change is how to display the RDocs for the core and 
standard libs.  Problem one is simply the layout, and I think the RDog 
project shows a much better approach.  Problem two is that the site does 
not offer a way for a reader to add annotations, such as with the docs 
at http://www.php.net/docs.php (often cited as a model of good on-line 
docs presentation).

My plan for this was to change the default rdoc template to include a 
javascript call that would make an XmlHttpRequest (AKA AJAX) fetch from 
a docs wiki page,  and dynamically insert the content of the 
corresponding page into the rdoc display.  Those without javascript 
would simply see a link to the wiki.

A decent, simple search engine would be quite nice, too.

Other items on the site (e.g., links to documentation bundles and useful 
resources for beginners) would  stay pretty much the same.

I'm open to ideas on how to make the site better, and really hope there 
is interest here in using this as an opportunity to showcase Og/Nitro.

Thanks,


James Britt
-- 

http://www.ruby-doc.org - The Ruby Documentation Site
http://www.rubyxml.com  - News, Articles, and Listings for Ruby & XML
http://www.rubystuff.com - The Ruby Store for Ruby Stuff
http://www.jamesbritt.com  - Playing with Better Toys