On 23.06.2009 01:20, Robert Dober wrote:
> On Mon, Jun 22, 2009 at 6:50 PM, Joel VanderWerf<vjoel / path.berkeley.edu> wrote:
>> James Gray wrote:
>>> On Jun 22, 2009, at 7:10 AM, Roger Pack wrote:
> 
>> To expand on James's proposal a bit... what about defining a module called,
>> for example, Socket::Tutorial, and putting the material in the comment block
>> of that module, for rdoc to find? Then:
>>
>>  `ri Tutorial` ==> list of tutorials(*)
>>
>>  `ri Socket::Tutorial` ==> the socket tutorial
>>
>>  `ri Socket::Tutorial.open` ==> tutorial on Socket.open.
>>
>> (*) actually, I'm not sure current ri performs a search for x::Tutorial, but
>> why shouldn't it?

> Honestly that sounds brilliant. I am just a little bit confused about
> the x::Tutorial, should that not be Tutorial::X
> for X in { Array, Module, Class, Exception, Enumerator, You::Name::It } ?
> 
> And Tutorial would be a module in the standard lib?

I do not like the idea.  Here's why: you add code which has the sole 
purpose of carrying documentation.  The primary purpose of source code 
is to provide functionality and not serve as a text skeleton.

The second reason is, that documentation derived from code typically has 
a different structure than "hand crafted" tutorials.  This documentation 
is structured around source code artifacts such as classes and modules. 
  A written tutorial focuses on tasks and usually has a structure so 
that you can more easily learn when reading from beginning to end.

Having said that it is probably a good idea to include tutorials in the 
standard distribution.  But IMHO they should be written as tutorials, 
probably using Textile markup or something similar.

My 0.02 EUR

Kind regards

	robert

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