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
> 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