[Nitro] Nitroproject.org

* William william.full.moon at gmail.com
Sat Feb 3 11:36:00 EST 2007


Hi men/women

There is a small challenge with this call for action.  The sands shift
beneath the documentation.  

> I would love, when everyone (even you, silent listener) could think of 
> at least one part he would like documented and respond here.

An earlier production on the NitroProject.org wiki held promise, then the
wiki links were all messed up -- and I am no longer sure 

   (a) what is still linked, and exists
   (b) what is incorrect or out-of-date and needs fixing 
   (c) what is new and thus missing
   (d) what is 'lost' and (or) disconnected from the supporting matter

.... Hmmm -- Lest this mail sound like a critique, I shall stop.  What I
really want to say is that fluid classes, etc can only be maintain
documentation on-the-fly by the author.  

Big picture stuff probably needs to lag one 'release' behind the leading
edge of agile development.  It is a well known fact that Smalltalk, c and
ruby were designed for terseness (where as English and most meat-languages)
are for intra-personal communication (rather than 'science' or
'engineering').  

A big thing that can be fixed is to NOT build the NitroProject.org web site
on the work-in-progress release (except for bug fixes).

My hand is on my heart.  At one time I worked in a environment were we
supported over 6,000 users on a product that is very similar in ethos to
Nitro.  You can't build the meta-documentation on an "in-progress instance"
of the product.  Please relax.  

All I'm saying is that before the documentation challenge can be satisfied,
we need a stable documentation project/platform (structure) as precursor.  

To make that happen all we need is some discipline around "release
management" and "migration" strategy.  If I may continue, part of the
solution is to have proposals written in NitroProject.org along side the
'current' documentation.  

That looks like a "design for ..." what's to come.  With some write-up of
what there now.  Personally I am unsure if Nitro is yet stable enough to
begin such a process.  I'm not really a product information person, I just
used to get hassled by them -- So my judgment could be flawed.  

My private utopia is a place where a Product Information person writes
documentation from the Unit Test and Systems Test cases.  BEFORE any one
writes any code. (*ohmygawsh*)

That would need to be CLEAR-ly delineated.  (I think my ultimate notion
here, could turn into a whole new "wiki" feature).  In the short-term, that
requirement can be satisfied by a "wiki versioning" system that permits
"labels" or "release tags" --Such that I might compare "now" with "version
-1" (etc.)

I didn't mean to launch into something weird ... I think there are some
useful points above -- And I think it is a group consensus that needs to
develop around HOW we document things  ;-)

Aloha,
        Will.


-----Original Message-----
From: nitro-general-bounces at rubyforge.org
[mailto:nitro-general-bounces at rubyforge.org] On Behalf Of
nitrojesus.5.pistos at geoshell.com
Sent: Friday, 2 February 2007 04:34
To: nitro-general at rubyforge.org
Subject: Re: [Nitro] Nitroproject.org
Importance: Low

On 01/02/07, Jonathan Buch - john at oxyliquit.de wrote:
> http://24.21.123.8:9000/
> I would love, when everyone (even you, silent listener) could think of 
> at least one part he would like documented and respond here.

More [short] screencasts, and beginner/intro level tutorials.  People need
to be able to dive in easily, so that they can get hooked on how great Nitro
and Og are.  :)

Things that I think tend to be good sales tools:
- Why Nitro? (and not something else)
- Why Og? (and not something else)

Perhaps add:
- Differences between Og and AR
- Differences between Nitro and ___

There should probably also be a cookbookish section for lookup of snippets
that answer "How do I <simple task>?"

For more advanced developers, maybe a graphical overview of the pipeline of
processing, from browser making HTTP request, to the innards of Nitro, all
the way back to the browser.  This would include what classes are involved,
etc.

Pistos
_______________________________________________
Nitro-general mailing list
Nitro-general at rubyforge.org
http://rubyforge.org/mailman/listinfo/nitro-general

-- 
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.5.432 / Virus Database: 268.17.12/655 - Release Date: 28-Jan-2007
13:12
 



More information about the Nitro-general mailing list