[Nitro] Keeping Documentation and Tutorials up-to-date
prpht9 at gmail.com
Fri Sep 14 11:04:02 EDT 2007
I just looked at Robert Mela's cheatsheets<http://robmela.com/cheatsheets>.
Those are perfect for going into the RDocs.
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
> 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
> 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...
More information about the Nitro-general