[Nitro] Documentation Documentation
transfire at gmail.com
Fri Nov 2 21:29:39 EDT 2007
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 the use case is this -- how do I generate that entry such that Arne
> can easily integrate it into what he's doing? Or should I just write a
> cheatsheet now, and Arne or whoever can use it as input for their own
> version of docs?
> One scenario I envision is that Arne is Documentation Tsar. Generating
> 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?
More information about the Nitro-general