I, Nitro

Ruby Apps Nitro
21

On Nov 2, 12:07 pm, Robert M. [email protected] wrote:

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?

That’s a good question.

First let me say though that I am pleased to see so much interest in
this thread, and especially volunteers for writing documentation.
Clearly there remains real interest in Nitro as an alternative to
Rails and other LAMP frameworks.

Before we can really start digging our heals in with docs though, we
need to get 0.50 out. 0.50 will serve as our first weigh station for a
stable API. At that time I will workout a more specific documentation
strategy. In the mean time, it would be useful to discuss the general
ideas of how a good doc process would work. And I think your question
goes directly to the heart of the matter.

I would say the first thing to do is check with community and head
developers to see if such a documentation case is already out there or
in the works. If it is, it may be better to help improve that, rather
then start another. But lets say there isn’t and the community
feedback is positive. Then the next thing to do is sketch a tutorial,
be sure to work through it a few times to polish it up, and the post
that to Oxy. Now that may be as far as it goes, which is fine --the
tutorial has contributed to the Nitro knowledgebase. However,
depending on the case, the tutorial might be able to go further and
turn into a section of The Book.

Of course, maybe you don’t want to do a tutorial and just want to make
a cheatsheet. Thats cool too. I think maybe adding a cheatsheet
section to Oxy would be a good idea. It would be interesting to see
how much we could turn something like this into an assembly processes.
Could one person create a text-based cheatsheet and another turn that
into a really snazzy graphical cheatsheet, or a screencast?

At the same time, the Doc lead(s) might read this material and use
some information in it to “back-improve” RDocs (which are docs for
programmers) or the API wiki (low-level docs for end users). They
would also be responsible for seeing that information on Oxy stays up-
to-date, well formatted, etc.

Ok. That’s just my first rough thoughts, on the matter. Yours?

T.

22

A couple of thoughts

On Nov 3, 2007 12:29 PM, Trans [email protected] wrote:

On Nov 2, 12:07 pm, Robert M. [email protected] wrote:

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.

Before we can really start digging our heals in with docs though, we
need to get 0.50 out. 0.50 will serve as our first weigh station for a
stable API. At that time I will workout a more specific documentation

Possibly off topic, maybe of interest, but worth stating explicitly -
I won’t have the DBI adapter ready for the 0.50 release.

that to Oxy. Now that may be as far as it goes, which is fine --the
tutorial has contributed to the Nitro knowledgebase. However,
depending on the case, the tutorial might be able to go further and
turn into a section of The Book.

Of course, maybe you don’t want to do a tutorial and just want to make
a cheatsheet. Thats cool too. I think maybe adding a cheatsheet
section to Oxy would be a good idea. It would be interesting to see

I think a cheat-sheet should be reasonable prominent, if it is task
oriented. Examples I like are the Sequel cheat sheet on their wiki
http://code.google.com/p/ruby-sequel/wiki/CheatSheet
and
the layout of the flexmock readme (early example and then cheat sheet)
http://onestepback.org/software/flexmock/

IMHO the Sequel style cheat sheet could fill in the place of the flex
mock ‘Quick Reference’.
It can be :include: <common_cheatsheet.file>.
This would mean every copy of the Nitro/Og would have a local copy?
I think it is worth some thought/effort to keep the RDoc and ‘other’
versions of this section common.

how much we could turn something like this into an assembly processes.
Could one person create a text-based

(or one in the RDoc readme?)

cheatsheet and another turn that
into a really snazzy graphical cheatsheet, or a screencast?

At the same time, the Doc lead(s) might read this material and use

the cheat sheet directly, and use

some information in it to “back-improve” RDocs (which are docs for
programmers) or the API wiki (low-level docs for end users). They
would also be responsible for seeing that information on Oxy stays up-
to-date, well formatted, etc.

It’d be great to try and find some way of keeping the docs as common
as possible, but apart from :include: in RDoc I’m not sure what else
can be done.

I’m not very familiar with AR so do not know of a ‘well/widely-know’
cheat sheet. If there is one, mimicking it sturcture (assuming it is
good/reasonable), would be a natural way of indirectly comparing AR to
Og?

HTH
Mark

23

We need to draw up a list of what formats we want to target.

A (START HERE) at the README RDoc level is a great idea. A README.intro
alongside the current README.og and README.raw.

What are the goals?

– install Nitro
– verify that it works
– proove: useful common things are really simple in Nitro

If those are the goals, does this achieve them:

Intro I ( README.intro )

  • single-file app ( with Controller and Dispatcher )
  • starting and stopping
  • canonical hello world app
    . nitro --create
    . a template
    . a controller
    . an element

Intro II ( Og ) ( README.intro2 )

  • Library example ( Book and Author ), using admin part
    ( or something similarly simple but more exciting )

Intro III (? or maybe this belongs in a tutorial )

  • Add a simple form to Intro II

At this point it’s pushing the limits to becoming a tutorial…

24

On Nov 3, 2007 12:40 PM, * William [email protected] wrote:

Hi gang

Personally speaking

i agree there must be a [START HERE] document like and induction set.

agreed and at the risk of repeating myself :wink: I think this
‘introduction level information’ is best done in the readme file,
which can be duplicated elsewhere, but the readme version should be
the reference point?
More extensive introductory material/howto can be refereed to.

Secondly I prefer a cook book approach to the second level USER
documentation.

BOTH these would be backed by solid PROGRAMMER level documentation.

Agreed. In fact since I always have the pickaxe book and the Ruby
cookbook on my desk I’d say that, for me, the best documentation
(book) would be the Ruby cookbook with the pickaxe appendices.
Is this a longer term target/structure worth setting and aiming for?
It would kill the two birds with one document/book.

HTH
Mark

25

What’s a “greenfield” app?

Also – not sure I’d want to enter competition with Rails and risk flame
wars and all… is it possible to talk about what Nitro does, with
examples, and leave it at that?

26

Forgot to delete the first spurious sentence – writing this while
serving part-time as climbing structure for a three year old.

27

One nice “up and running” tutorial for Rails is this:

http://rails.homelinux.org/

It’s a bit dated by now, but covered out-of-the-box Rails experience.

Hope this helps.

28

So is that something in between Tutorial and Book.

  1. Quickstart (README.intro )
  2. Tutorial
  3. “Four Days of Nitro”
  4. The Book

Advantage – it appears long before “book”, and makes a great warmup for
person(s) doing Book.

Somewhere outside the progression but perhaps sharing some resources
with it

* Reference ( is this not the same as RDocs? )
29

On Nov 3, 2007, at 7:56 AM, Robert M. wrote:

What’s a “greenfield” app?

From scratch: Greenfield project - Wikipedia.

Also – not sure I’d want to enter competition with Rails and risk
flame wars and all… is it possible to talk about what Nitro
does, with examples, and leave it at that?

Don’t get me wrong. I love Rails. It’s all I use now. But the risk of
not acknowledging history for new endeavors is that you will repeat
it. No flame wars intended, but there are places where even Rails
doesn’t fit well.

30

Whilst we are on the subject of Og, here’s a request that came from
inside
ThoughtWorks. I’m interested in how it fits into the current model for
Og:

I want unit of work so that I don't have to manually remember to flush to the database or remember arcane rules about persistance through reachability for different collection mappings.

I want Hibernate-style HQL so I can perform complex reporting style
queries
expressed in my domain language and so that I can map legacy schemas
without
having to remember ugly table/column names.

I want several levels of caching so that I can be clever about caching
data
for read-mostly applications. (And anyone telling me ActiveRecord or
plugins
can already do this does not know what they’re talking about.)

Thoughts?

How much effort would it be to integrate a Unit-of-Work pattern into Og?
Or
should I be thinking about a whole other ORM here? As for the HQL-style
queries, I would prefer to see an embedded DSL that supported
database-independent queries, something like LINQ meets HQL. Perhaps
that’s
a separate project that would play nice with Og?

Thanks,
Dan

31

Hi,

So, having no shame, I’ll ask a stupid question: Why Dictionary for
request params? Also, does using Dictionary for some collection (
post/get params ) and Hash for others ( headers) risk being
counterintuitive? I think it’s reasonable to think of headers and
params as collections, and for a programmer to expect them to expose the
same syntax.

Is there a reason for these to maintain order?

there IS a good rason for the order: parameter munging how I call it.
(I’m reciting from memory, bear with me). A long time ago I created a
1000+ line test case covering the dispatcher exactly because of that
reason.

George wanted to be able to do the following:

/foo?a=b&c=d

def foo(a, c); [a, c]; end # => [“b”, “d”]

Whereas I still think even today that this is completely unnecessary,
wack, generally unclean implementation wise and leading to problems.

Without parameter munging it can be emulated this way:

def foo(a = params[‘a’], c = params[‘c’]); [a, c]; end # => [“b”, “d”]

But, as the story goes, George really wanted those and we finally
agreed on having it as an option, where I battled through that it
was not enabled by default, good.

Ayway, back to the Dictionary. Hashes are unordered, leading to the
weirdest errors with parameter munging. So, Dictionary it is until
parameter munging gets extinguished or else all hell will break loose.

Late, but anyway,

Jo

32

I’ll take a novices stab at this… if only to be corrected/learn
something :wink:

On Nov 5, 2007 9:16 PM, Dan N. [email protected] wrote:

Whilst we are on the subject of Og, here’s a request that came from inside
ThoughtWorks. I’m interested in how it fits into the current model for Og:

I want unit of work so that I don't have to manually remember to flush to the database or remember arcane rules about persistance

I think the persistence unit of work is an object instance - I posted
my first attempt to use Og by hacking someone’s AR performance
benchmark code. I tried to set out all the ways I could find to
‘create records’. IIRC, some just took an instance of the object or a
hash and stored it, others you had to klass#save.
Is this what the person above means?

through reachability
for different collection mappings.

Huh, sometimes I know I’m dense, and this is one of those times. It
sounds sophisticated so I’ll leave it alone.

I want Hibernate-style HQL so I can perform complex reporting style queries
expressed in my domain language and so that I can map legacy schemas without
having to remember ugly table/column names.

I’ve never used Hibernate… sounds like the author wants Og to know
their domain language? Or, do they want to be able to pass blocks to
Og queries?
Og allows legacy tables I’ve not used them but a mail list/Oxyliquit
search should throw something up.

I want several levels of caching so that I can be clever about caching data
for read-mostly applications.

Not as far as I know, but after learning that Caboose::EZ apparently
(who would have quessed) contained some query DSL methods I’m
reluctant to say that something is not in Og :wink:
The Sequel project mentions caching, so have a look at that in the mean
time?

(And anyone telling me ActiveRecord or plugins
can already do this does not know what they’re talking about.)

Thoughts?

How much effort would it be to integrate a Unit-of-Work pattern into Og? Or

If by unit of work you mean something like a dataset/recordset then
that might be realized once I’ve finished plundering Sequel’s code
base - but that is vapor ware at the moment.

should I be thinking about a whole other ORM here? As for the HQL-style

Have a look at Sequel for immediate needs. I’m hoping to incorporate
the dataset, querying, filtering and caching goodies therein.
The model management approach and syntax is quite different from Og,
but hopefully the rest of the syntax will be common (?).

queries, I would prefer to see an embedded DSL that supported
database-independent queries, something like LINQ meets HQL. Perhaps that’s
a separate project that would play nice with Og?

I’d be interested in hearing thoughts on Sequels approach to caching,
datasets, querying vs Og’s or any other.

Cheers
Mark