On 24.06.2009 00:00, Roger Pack wrote:
>>> Having said that it is probably a good idea to include tutorials in the
>>> standard distribution. �Âut IMHO they should be written as tutorials,
>>> probably using Textile markup or something similar.
>> Not a bad idea at all. I would prefer to write it in textile rather
>> than in rdoc.
>> However I still feel it would be great if we could incorporate Jo�ì's
>> idea of linking it into the "right" place.
>> What'u think?
> 
> Chiming in, I quite like the idea overall of having Tutorial's 
> accessible via ri, since you could use ri to view it and then use ri to 
> lookup methods--you'd only need one tool overall.

For me that is not an advantage.  For me a tutorial is something that 
has been written with the reader's learning curve in focus and not with 
the structure of software.  That is completely logical because when 
reading a tutorial I might not know what classes will implement 
particular functionality.  I'm all for tutorials but please don't mix 
them with reference documentation.  If at all, have tutorials link 
reference documentation.

> The concern is that the tutorials would clutter the code, is that 
> correct?

Partly.  The other half is that I have certain expectations about how a 
tutorial is written (see above) and placing them in code reference 
documentation makes it harder to find for the novice.

> The benefit of this not being "oooh we get to use rdoc syntax!" but more 
> "we already have a command line browser for it, since we can use ri."

I doubt that ri the proper tool for the job.  We'd rather need something hich can present a table of contents and is capable of doing full text 
search on it.

> Another benefit is the tutorials will likely show up in the rdoc's too.We would be able to achieve that witch external links as well, don't we?

> Another question is how to preserve a wiki-like feel to the tutorials. Well, you can do that only with a Wiki not with something distributed 
with the source code.

> I know google code projects commit wiki changes as svn commits but...I'm 
> not sure how this could work for core.  Any thoughts there?  Just 
> include instructions somewhere on how to update them maybe?

A tutorial wiki on ruby-lang.org or a related place sounds good to me. 
Usually Wiki engines nowadays have versioning so that shouldn't be a 
problem.

Kind regards

	robert

-- 
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/