[Nitro] File adapter for Og

[James Britt]

Dan Yoder wrote:
 > I would like to stress how badly needed this kind of documentation is
 > ... i realize, of course, that i am stating the obvious, and the equally
 > obvious response is to do like james and write some of it.
 > unfortunately, i don't have the time (at least right now) to do this,
 > and the lack of documentation is making it difficult to make progress
 > with nitro.

Truth is, I started writing the tutorial to help me use Nitro.  Writing 
helps me think; if you want to know want you really think or know about 
something, try writing it down.

 >
 > so what i am wondering is where is this on the agenda? what is the
 > estimated time frame for this? are there other folks working actively on
 > documentation? is there a to do list?

I'm getting close to sending something off to George.  It does not cover 
all aspects of Nitro; I don't even know what that would entail.  The 
goals of the tutorial are to encourage use of Nitro, and demonstrate a 
methodology of design and development facilitated by Nitro.

I decided to send time with Nitro for variety of reasons: curiosity; 
disgust with the prevalent "Mine's bigger" pissing contest driven by 
many in the Rails community (and little apparent interest from anyone in 
toning it down or reigning it in); a suspicion that Nitro did in fact 
offer a valuable alternative to Rails.

Hopefully, my doc will clarify that last point.  Rails has some great 
features, stuff worth stealing to be sure.  But it presumes an awful lot 
about your application design process and architecture.  I might very 
well be wrong; Rails is remarkably complex, so for all I know it has a 
way to do everything I see in Nitro, but so far I haven't found it.



 >
 > again, please understand this is in NO WAY meant to slam the current
 > effort. g & co are doing great work moving this forward and it is great
 > to see the activity on the list picking up. i am just asking the
 > questions to try and better understand where we are at. =)

Lots to do.  We have the mixed blessing of working with a framework 
still in progress.  The nice thing is that there is time to change 
things before they get to entrenched.

For those playing along at home, here are some possible ways to contribute:

* Post to the list when you find something unclear or unintuitive. 
Sometimes simply changing the name of something can be a big step, but 
users need to speak up

* Write docs for methods you understand.  If you look at the rdoc for 
Nitro you find very few comments.  The method names aren't, to me, 
immediately self-explanatory.  If you've used something and think you've 
gained some insight, offer up an rdoc comment for the method.

* Write simple examples that highlight one or two features.

 >
 > ~dan
 >
 > p.s. one thought i have is a similar tutorial in the spirit of what
 > james is doing, but converting a rails app to nitro. this could also
 > address why you might want to do such a thing. =) i could potentially
 > write or contribute to this, since that is a big part of my struggle.

Sound nice.  BTW, I really hope not to see any (well, too much) Rails 
sniping here.  I've used it, I've made money off it, there are many 
good, smart people working on it.  But it may not be suited for all 
cases, and people should have and understand the alternatives.  It would 
be nice if you wrote up some guidelines or lessons learned from Rails 
porting.

 >
 > p.p.s. another rails-related thought: i think a lot of the documentation
 > for rails is actually pretty weak. there is plenty of it, but some of it
 > is badly out of date and there are a lot of really basic kinds of things
 > that are not addressed well. i think a really strong set of tutorials
 > and cookbooks could really help nitro's adoption.

Docs is hard!  Especially as things change.  Nitro docs I wrote this 
morning are out of date.  Code samples really help.  Here's a thought: 
Is there am automated  tool that lets you store a set of code samples, 
unit test them, then publish them as HTML, with annotation indicating if 
a sample failed any tests?  As Nitro/Og progresses, the cookbook would 
be run against the latest versions, and any out-of-date samples flagged. 
  I hate copying code, trying out, having it fail, only to learn that it 
will never work with the current version.

On a related note, my tutorial has, so far, made no mention of unit 
testing.  I'm planning on suggesting that code of any complexity should 
  be encapsulated into clearly defined classes that are easy to test 
independent of the Nitro environment; you shouldn't have to run a server 
to test the code.  Any thoughts on Nitro/Og unit testing?

James