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

On Tue, Jun 23, 2009 at 11:30 PM, Robert
Klemme<shortcutter@xxxxxxxxxxxxxx> wrote:
On 23.06.2009 01:20, Robert Dober wrote:

On Mon, Jun 22, 2009 at 6:50 PM, Joel VanderWerf<vjoel@xxxxxxxxxxxxxxxxx>
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.
And what if documentation were the functionality of this code?
IMHO it is completely open if there would be code or only rdoc
documentation, but nicely included into the class hierarchy. Joël has
probably an idea about that.

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.
You are absolutely correct, but please see above, no code as far as I
am concerned.

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.
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ël's
idea of linking it into the "right" place.
What'u think?

R.

.

Relevant Pages

  • Re: collection of a class
    ... Second, you should know that the collections classes and just about everything else in the Java world is heavily documented, and where to find the documentation. ... and API documentation ... both the tutorials and the API docs give a good introduction: ... coll.add(someTypeThing); ...
    (comp.lang.java.programmer)
  • Re: Installation von Emacs 22.1 und Gnus unter Windows
    ... Weggelassen habe ich alle Beschreibungen zu Sonderbedienweisen zum ... welche Tutorials ich durchgearbeitet habe.) ... Hat mir in anderen Texteingabeumgebungen gefehlt. ... Documentation> Search Documentation String C-h d", ...
    (de.comp.editoren)
  • Re: Id RTFM if they actually GAVE me a FM!!
    ... >> documentation, and that's quite often true for Borland's docs as well. ... principle early in tutorials. ... advanced components is "most of the basics but few specialized terms and the ... You took my suggestion to Google for a tutorial far too personally and far ...
    (alt.comp.lang.borland-delphi)
  • Re: collection of a class
    ... Since you admit that it's homework, I am happy to provide hints. ... and API documentation ... both the tutorials and the API docs give a good introduction: ... coll.add(someTypeThing); ...
    (comp.lang.java.programmer)
  • Re: Improvements to RDoc (ideas for GSoC)
    ... and work on something related to RDoc. ... information on a specific feature, and a more general documentation, ... don't really need the second part, but as I was designing a ACL plugin ... This kind of layout is already implemented by Noobkit. ...
    (comp.lang.ruby)