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

chris prpht9 at gmail.com
Fri Sep 14 11:01:25 EDT 2007


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/c93bf5df/attachment-0001.html 


More information about the Nitro-general mailing list