[Nitro] A Request for Help

Michael Fellinger manveru at valaraan.de
Tue Sep 20 18:17:42 EDT 2005

James Britt wrote:

>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 
>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.
I guess you know the examples spark and flare already... they are not 
exactly what one would call complex, but they are very good to study and 
learn (almost, one can't get everything on one page i guess) everything 
about nitro and a few things about og as well.

>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.
Your idea sounds interesting, and i wondered already how that page works :)
However, i saw a website with all kinds of categorized rss-feeds about 
ruby some time ago.... i just can't remember it anymore, but it looked 
good for further collection.
But there are two ways you could go - a bit manually or automagically.
So, getting a community to serve news is one thing, wich has happened 
now - i can't even read or track everything of it (i read Technorati 
with everything related to ruby and the ML), that is something i really 
miss from the beginning... (wasn't that long before).

Well, one could just collect everything about ruby from blogs, news and 
so on, get it into a queue and some moderators check it if they like it. 
this would be the manually process - the automagically will have to 
unite some very very good ideas about information-relevance and like... 
you don't want information that is important to be filtered, i guess 
this could be solved by using a bayesian filtering, wich we would have 
to watch, but that does most of the work on its own.
There are very good spam-filters out there, and i think we could 
implement one in ruby too, based on something like spamassassin.
The only problem i see with this is that ruby may be widespread over too 
many topics already, i guess we just have to try that one.

>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).
Well, the way to add annotations should be the wiki. it was planned to 
add the article of the wiki, or maybe an extract between special 
[doc]tags[/doc] on the page of the doc.
it is not implemented yet and there are some (good) reasons for that.
First of all, the DocController is not merged with the WikiController, 
so they have no common database and don't share anything (except the skin)
This is because the DocController has nothing to do with Og, it is base 
on yamls instead - this will change as soon as the problem with the 
inheritance in og is solved (giving george a broad hint ;)
next thing is that i'm not sure how to merge them later and if it would 
be better to split the whole thing (possibly not) into smaller parts 
like 'nitro/og', 'glue', 'core/stdlib' - you get the idea...

>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.
i like XmlHttpRequest... but this happens not only to everyone without 
javascript, but also to every lucky IE-surfer who has ActiveX off (about 
99% of them - the others don't survive)
well, and doing this the normal way is no problem either, so why bother 
with ajax?

>A decent, simple search engine would be quite nice, too.
It is planned and will get implemented ASAP, but searching through yamls 
is a pain, you know? :)

>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.
>James Britt
Hey, i would love to help you indeed, i want ruby-doc.org to become the 
new standard in documentation (leaving php.net behind) :)
But i guess we have to wait for the next version of nitro/og.

Another thing i have stumbled upon is something much more trivial but 
really important.
The standard-stuff, like if/else, loops, iterators and like, it is 
described in the book, but there is no unified documentation on them 
(found some tables comparing the syntax to other languages, but that is 
not what i want)
I know this is not php (and that's good), but i like the idea to give 
comments on these topics as well.

so long...
Michael 'manveru' Fellinger

More information about the Nitro-general mailing list