[Nitro] Documentation

James Britt james_b at neurogami.com
Thu Sep 1 14:45:30 EDT 2005

Peter Abrahamsen wrote:
> I would expand on this to say that, IMHO, Nitro+Og+... s in desperate  
> need of good documentation. The rdoc and walkthroughs are valuable,  but 
> they don't replace real documentation. Real documentation would  have a 
> bunch of best practices for all common tasks, as well as  listings of 
> all the tools you have in different contexts. Some of  this could be 
> built into the rdoc, but there ought to be several  starting points 
> outside of the source code or module structure.

Good docs are a weak point for many, of not most, OSS applications and 
libs.  For various reasons, those most familiar with the code tend to 
spend more time writing code than docs.

> It's been frustrating trying to learn how things work browsing either  
> the source or the rdoc modules list. I can only find the information  
> I'm looking for once I understand how the code works and is laid out,  
> and even then it's spread out between too many files and modules. I  
> don't think I should have to do that.

Ideally, no.  For the time being, yes.  But people are working on 
changing that.

> The constant stream of good, new features is impressive, but I think  
> that some excellent documentation would do a lot to bring more people  
> on to the project. Maybe that's where you're heading already, maybe  
> you're waiting for the API to settle more before 1.0, I don't know.

I had started on Nitro: Step-by-step some months ago, then put it on hod 
while the API was setting down.  Now I just need to find enough time to 
go back and get it done.

> I feel like it'll be some time before I understand Nitro well enough  to 
> write best practices or reference docs, but maybe there's  something I 
> can do to help. Let me know.

I think, if nothing else, it might be handy to track what are the common 
uses cases and scenarios people want to know about, so that people can 
get up and running on the more common jobs.



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

More information about the Nitro-general mailing list