[Nitro] File adapter for Og

James Britt james_b at neurogami.com
Tue Apr 5 19:50:30 EDT 2005


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.

Essentially, I had no good idea of where to start with Nitro.  The 
tutorial fixes that.

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 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.  For 
example, my tutorial shows conditional render of a common header file by 
using the new @parent_action_name.  Nothing earth-shattering, but simple 
and useful, both for accomplishing a task and demonstrating syntax.

> 
> ~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, 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.  The 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 code 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




More information about the Nitro-general mailing list