[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*.
> >

<snip>

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

> 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