[Nitro] Documentation Documentation

Mark Van De Vyver mvyver at gmail.com
Sat Nov 3 02:51:16 EDT 2007

A couple of thoughts

On Nov 3, 2007 12:29 PM, Trans <transfire at gmail.com> wrote:
> On Nov 2, 12:07 pm, Robert Mela <r... at robmela.com> 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*.
> >


> > 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

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

> 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

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
the layout of the flexmock readme (early example and then cheat sheet)

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


> Ok. That's just my first rough thoughts, on the matter. Yours?
> T.
> _______________________________________________
> Nitro-general mailing list
> Nitro-general at rubyforge.org
> http://rubyforge.org/mailman/listinfo/nitro-general

More information about the Nitro-general mailing list