Re: ruby suggestion: officially sanctioned tutorials/howto's

On Wed, Jun 24, 2009 at 4:05 PM, Roger Pack<[e-mail]> wrote:
>>>>> What'u think?
>>> reference documentation. =A0If at all, have tutorials link reference
>>> documentation.
>>
>> True, but I do not see why integrating it into ri/rdoc and the
>> distribution would need that, there might be
>> Tutorial::Network, Tutorial::HowToCookEggs and Tutorial::Array. This
>> is very much inspired by Perl's way to do these things, but they did
>> this quite well. I was able to get real work done with the perl pods
>> and perl tutorials which were perfectly integrated.
>
> Perhaps you could help me by explaining how perl did it so nicely and
> how the integration worked?
Interesting thought, I admit that this might have been a jumped
conclusion, maybe it was hard work behind the scenes. But my thought
was that they just created .pl files full of POD?
> For my own $0.02 I would imagine having the Tutorials in with the normal
> rdoc would be an advantage--you could browse them while browsing the
> rdoc. =A0Feels more accessible somehow.
>
> One option to avoid clutter would be to force everything into the
> Tutorial root module [kind of like the Tutorial namespace], then it
> would be close to the code but not integrated.
I
>
>
>>> Partly. =A0The 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.
>
> Well rdoc does give us somewhat of a layout in terms of class names. =A0I
> had thought we could just use module names for sections, like
>
> Tutorial::Arrays::Chapter_1
> Tutorial::Arrays::Chapter_2
>
> etc.
>
> someone could link to Tutorial::Arrays if they wanted to see the whole
> thing. =A0I assumed it would be about as easy to navigate/find as any
> indexed layout. Thoughts?
>
>
>>>> The benefit of this not being "oooh we get to use rdoc syntax!" but mo=
re
>>>> "we already have a command line browser for it, since we can use ri."
>>>
>>> I doubt that ri the proper tool for the job. =A0We'd rather need someth=
ing
>>> which can present a table of contents and is capable of doing full text
>>> search on it.
>
> Good point. =A0For me the nicety would be in rdoc integration, not ri
> integration [I never use ri].
>
>
>>> 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.
>>
>> To me too, I am not saying that the Tutorial::OMG::RubyIsSoCool is the
>> only solution, I just feel that you
>> reject it for reasons that do not really exist.
>> What is great is that it integrates nicely with the distribution, I
>> imagine "sudo gem install ruby-tutorials" or
>> "sudo gem install ruby-tutorials-ruby-is-cool" and nobody would need
>> to learn yet another URL. It was a real
>
> Would gemifying stuff be helpful or are you just pointing out that
> integration with existing tools takes out the need for another tool?
> Just wondering.
>
>> speed up factor for me to learn Perl when I found all I needed at the
>> same place. Again if we put a wiki to ruby-doc that will probably
>> serve the same purpose.
>
> There is somewhat of a wiki:
> http://en.wikibooks.org/wiki/Ruby_Programming [it's even linked to from
> deep within the nether-reaches of the ruby-lang.org website]. =A0Another
> option might be to just flesh that out and call that the tutorial. =A0Man=
y
> of the things it has are things that could belong in a Ruby
> tutorial--ex: basics of an Array. =A0Of course it's missing things that
> might be quite useful, like "how to use -rdebug", "how to use openssl",
> "how to use -rtracer" etc, so obviously it's far from complete
> currently. =A0The kicker is that it seems like if we put tutorials there,
> [ex: openssl] we'd end up explaining the methods we use as we use them,
> duplicating the existing rdoc, so a tutorial closer to [and
> supplementing] the rdoc might be easier to write.
>
> I did notice from http://webri.tigerops.org/ that many classes [ex:
> BigDecimal] already have tutorial like information in the class
> description. =A0For some reason that information isn't in the rdocs I'm
> not sure why [1]. =A0I suppose that means that an option is to put all
> tutorial information into the class' rdocs...
>
> Anyway the wiki and the ri are "related projects" to a tutorial system
> thought I'd point them out.
>
> Thoughts?
> =3Dr
I am a little bit confused about some of the quoting, my fault my post
really was too long, but I like what you propse. I also like what
Robert proposes, I just want to defend the Tutorial namespace thing he
refuses. Correct Robert?

Cheers
R
--=20
Toutes les grandes personnes ont d=92abord =E9t=E9 des enfants, mais peu
d=92entre elles s=92en souviennent.

All adults have been children first, but not many remember.

[Antoine de Saint-Exup=E9ry]