[Nitro] Documentation Documentation

Robert Mela rob at robmela.com
Fri Nov 2 12:07:11 EDT 2007

The Og/Legacy DB question offers a good use-case scenario for the 
documentation process.   It was next on my list for cheatsheets, so I'm 
already willing to generate *something*.

So the use case is this -- how do I generate that entry such that Arne 
can easily integrate it into what he's doing?  Or should I just write a 
cheatsheet now, and Arne or whoever can use it as input for their own 
version of docs?

One scenario I envision is that Arne is Documentation Tsar.   Generating 
documentation himself, but also farming work out to other volunteers.   
I'm willing to write submissions as they occur to me, write submissions 
as per DocTsar requests, or do legwork and research, legwork, code 
reading, and experimentation for things anyone else is thinking about 
writing about.

So, let's take Og and Legacy Databases as a use case scenario for a 
documentation process and me as an example volunteer.  How might a 
process work?

Dan North wrote:
> I'm really excited about this. There is already a buzz inside 
> ThoughtWorks about this announcement. It would be great to see a 
> genuine viable alternative to the rails / active record world.
> I see nitro having two significant advantages over rails:
> * It is just so easy to use. I really do struggle to get my head 
> around rails. There is a surprising amount of hidden "tacit" knowledge 
> required to become effective with rails, given that it is supposed to 
> be entirely convention based. I describe it as the difference between 
> struts and webwork (for anyone from a Java background). Struts was ok, 
> and was the framework that made java a viable web technology, but 
> webwork just feels nicer. (Ironically, "struts 2" is actually webwork 
> 2 - so they eventually worked that out for themselves).
> * I can write a web app that talks to a legacy database. Og gives me a 
> full ORM rather than requiring that I own the database. That opens up 
> a whole class of web apps that are simply not available to a stack 
> constrained to an active record pattern.
> For my money (about $0.02), this would be my priority for getting 
> nitro "out there":
> - Documentation, documentation, documentation. It doesn't have to be 
> clever or comprehensive. Just a solid walk-through of creating an 
> application. The answers are mostly there amongst the original videos, 
> the cheat sheets and the tutorials. It just needs shaking down and 
> presenting in a clear and consistent way. I would choose some 
> "typical" users  and target them. Initially target an experienced ruby 
> programmer writing their first web app in nitro. Then something like a 
> "nitro for rails developers" track.
> - Stability. (Funny enough, less important to me than being able to 
> write an app in the first place.) I don't mind if it has rough edges 
> as long as the core stuff mostly works, and the mailing list is 
> responsive to my stupidity. It's pre-1.0 after all.
> Cheers,
> Dan

-------------- next part --------------
A non-text attachment was scrubbed...
Name: rob.vcf
Type: text/x-vcard
Size: 116 bytes
Desc: not available
Url : http://rubyforge.org/pipermail/nitro-general/attachments/20071102/b50683a5/attachment.vcf 

More information about the Nitro-general mailing list