[Nitro] Documentation Documentation
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
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
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.
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 116 bytes
Desc: not available
Url : http://rubyforge.org/pipermail/nitro-general/attachments/20071102/b50683a5/attachment.vcf
More information about the Nitro-general