[Nitro] Oops, and documentation idea...

chris prpht9 at gmail.com
Thu Oct 4 15:07:12 EDT 2007


  This is similar to something I mentioned awhile back.  And it has one
particular issue.  The documentation does not evolve and get transported to
users when they do, say... "sudo gem install og --version= 0.40.0" or
however you would type this for a specific version. (don't feel like looking
it up)  Including og and nitro documentation in rdoc along with the code
accomplishes your goal and it keeps all evolving changes to documentation
with the pertinent code.  Tutorials should be a part of the rdoc
documentation is what I'm saying.  Oxyliquit provides a place for users to
post tutorial ideas and the base ones, like your cheatsheets get installed
with every gem.

  As for the collaborative documentation aspect, I'll have to think about
that for a bit.  The back of my head is screaming wiki with an automated
export into darcs that only george can kick off.  I'll post back when I have
some more defined ideas.

  I would be willing to post an example of what I propose to this list for
you guys to consider.  I know this doesn't necessarily associate the comment
threads like on the php docs site you mentioned, I'd have to put more
thought into that than I have available brain power currently.

Just my 2cents


Below is the comment I made a while back about documentation called "Keeping
Documentation and Tutorials up-to-date"

Hi all,
>   A methodology recommendation has been rolling around in my head for a
> few days now and I'd like to bring it up here on the mailing list.  So, I'll
> get started with a little background and a question.
>   I was reading a post earlier today called "The basics" and want to ask
> the question "Where are the new tutorials going to be published?".
>   This seemed like an innocent enough question until i realized, your
> probably going to put it on OxyLiquit <http://oxywtf.de/>.  I'm not going
> to knock putting them there, it's actually one of the top locations new
> users are going to look for that information.  The problem I see is the same
> thing that happened to the other 4 tutorials.
>   They went out of date almost as quickly as they were posted.
>   I would like to make a recommendation to the Nitro/Og (raw, etc, etc.)
> team.  How about rolling a basic tutorial into the RDocs.  IMHO the
> situation your team is running into is a knowledge transfer gap between the
> creators and the intermediate to expert users of Nitro, not the newbies who
> barely know where to start.  Rake's RDoc index page<http://rake.rubyforge.org/>is a good example of what I think Nitro's should look like.  It gives all
> the information a newbie needs to get their feet wet and attempt to get to
> an intermediate level of understanding.
>   What the expert users needs is good reference material that explains the
> inner workings of how the components work with each other and small examples
> of how someone can utilize them.  eg: Rake::RDocTask<http://rake.rubyforge.org/classes/Rake/RDocTask.html>and
> Rake::GemPackageTask<http://rake.rubyforge.org/classes/Rake/GemPackageTask.html>
> These examples do not need to be easily understood by a novice.  However,
> they do need to effectively communicate a technical concept to a competent
> ruby developer without having to delve too deeply into the code to
> accomplish something.   I'm not saying they won't run into exceptions trying
> to get it working, but they should know what is possible with the class or
> module.
> note: I used rake just because it's something I picked up fairly quickly
> due to the rdocs.
>   The advantage of taking this approach to documenting your projects is
> you create a basis for the expert users to write the tutorials.  They could
> write them on their blogs, (good for your google ranking), on Fora or on
> OxyLiquit.  I'm basically saying, you should not be writing full blown
> tutorials, but moving smaller examples of how to perform actions into your
> RDocs.  This has key advantages...
> 1 - When a developer makes a change to the code they can make the example
> adjustments without having to open another editor.
>   eg: Or even better, without having to open a web browser, login to a
> wiki ( whatever ) and then make changes.  Way too many steps.  Developers
> are lazy, I mean efficient.  (tongue in cheek)
> 2 - The examples for a particular version of each project are in revision
> control with the code they reference.
>   eg: someone can download x.x lower version of the project and have the
> correct examples for that version
> 3 - The published RDocs can be available through your website and through
> ri without you having to publish yet another piece of documentation.
>   eg: rake deploy is all it takes (if you use newgem, not sure if you do)
> 4 - Patches from your userbase don't have to be just code, they can be
> updates to your tutorials as well.
>   eg: In fact if I were in your shoes, the first page of the RDocs would
> reference a page on how to submit updates to the examples as a patch.
>   As a final note, I would like to say the HelloWorld example from the
> repository for nitro-0.50 is a perfect starting point to put in the
> RDocs.  Then you could work the Blog example in for each of the components
> you want to communicate howto ___.  I'm all done ranting.
> Criticism always welcome,
> Chris Scheper

On 10/3/07, Robert Mela <rob at robmela.com> wrote:
> Sorry... I misunderstood the question... I'm up to my eyeballs in
> exploring Og right now, and its filtering everything I see.  I look at
> my wife and kids and visualize the generated foreign key attributes that
> join us.... :)
> Thanks for the kudos.    What I'd like more than my cheatsheets is a
> collaborative effort to produce documentation similar to the PHP docs --
>    http://www.php.net/docs.php.   I see it as a nitro app, with content
> in DocBook or something similar.   Perhaps Nitro elements could be
> created named similarly to DocBook elements, such that the docbook pages
> can be served up directly, as-is.    The same pages could be used later
> to generate a print book -- produced by a community(!) with proceeds
> going back to the project.
> Would someone be willing to host that in a mercurial or darcs archive?
> thx.
> Robert Mela wrote:
> > Some of the relation declarations are for the benefit of Og in schema
> > generation.
> >
> > Others are for the benefit of Forms in generating form elements to
> > bind relations ( see the views in nitro/part/admin/og )
> >
> > Arne Brasseur wrote:
> >>
> >> G, is this known/intended? If so it should be documented. Robert, you
> >> could perhaps add this to your cheatsheets? Very nice work BTW! I'm
> >> using them all the time now.
> >>
> >> http://robmela.com/cheatsheets
> >>
> >> (ab)
> >>
> >>
> >
> > _______________________________________________
> > Nitro-general mailing list
> > Nitro-general at rubyforge.org
> > http://rubyforge.org/mailman/listinfo/nitro-general
> _______________________________________________
> Nitro-general mailing list
> Nitro-general at rubyforge.org
> http://rubyforge.org/mailman/listinfo/nitro-general
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://rubyforge.org/pipermail/nitro-general/attachments/20071004/1876495e/attachment-0001.html 

More information about the Nitro-general mailing list