[Nitro] Keeping Documentation and Tutorials up-to-date

[chris]

Ok,

  I just looked at Robert Mela's cheatsheets<http://robmela.com/cheatsheets>.
Those are perfect for going into the RDocs.

Chris


On 9/14/07, chris <prpht9 at gmail.com> wrote:
>
> 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
>
>
> ----------------------------------------------------------------------------
> "If you project isn't using rspec <http://rspec.rubyforge.org/> and
> rbehave <http://dannorth.net/2007/06/introducing-rbehave>.  it should<http://rspec.rubyforge.org/rdoc/index.html>
> ..."
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://rubyforge.org/pipermail/nitro-general/attachments/20070914/ea301c7e/attachment.html