Forum: Ruby ruby suggestion: officially sanctioned tutorials/howto's

Current situation:

I remember way back when using the official python tutorial, there was
a section explaining the proper use of select with sockets, etc [1].
This was quite helpful to me getting started with the language, having
a more "tutorial" feel place to explain how socket IO should work
[i.e. larger snippets than the current rdoc has, place to explain
nuances, etc.]

The current rdocs [2] are useful and contain a lot of very helpful
information, but for me I currently have to already know the name of
the method I want to learn about for them to be useful [there is no
guide, little hierarchy [class based only], no "officially sanctioned"
place for things like longer tutorials, etc.]


I would like to suggest a more "officially sanctioned" Ruby
tutorial/howto to try to help fill that void.  Whatever that might
mean [official editable wiki page for it, a folder in svn that has
tutorials only, whatever].  I would be quite happy to help--set it up,
maintain it, or even write it myself, should such an idea be accepted.

Another option might be to add very long, tutorial style rdoc comments
to classes.

Thoughts?
Thanks.

=roger

[1] http://docs.python.org/tutorial/ specifically
http://docs.python.org/dev/howto/sockets.html
[2] http://ruby-doc.faithpromotingstories.org/doc/ruby-1.9.1-p129 or
http://ruby-doc.org/core-1.9/index.html

On Jun 22, 2009, at 7:10 AM, Roger Pack wrote:

> I would like to suggest a more "officially sanctioned" Ruby
> tutorial/howto to try to help fill that void.

I think this is a very good idea.

I was just thinking the other day about how I really like that perldoc
can do more than just look up method definitions.  For example, it can
search Perl's FAQ for you.  I realize that's not exactly what you are
suggesting here, but I found it useful in a similar way during my time
in their camp.

> Another option might be to add very long, tutorial style rdoc comments
> to classes.

We could create a tutorials folder in the main distribution, write
RDoc marked-up tutorials in there, and add those files to the
documentation build.  I'm not sure that's the best possible strategy,
but it is one idea.

James Edward Gray II

James Gray wrote:
> On Jun 22, 2009, at 7:10 AM, Roger Pack wrote:
>> Another option might be to add very long, tutorial style rdoc comments
>> to classes.
> 
> We could create a tutorials folder in the main distribution, write RDoc 
> marked-up tutorials in there, and add those files to the documentation 
> build.  I'm not sure that's the best possible strategy, but it is one idea.

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?

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:
>>>

> (*) actually, I'm not sure current ri performs a search for x::Tutorial, but
> why shouldn't it?
>
> --
>      vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407
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?
Cheers
Robert


--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

James Gray wrote:
> suggesting here, but I found it useful in a similar way during my time 
> James Edward Gray II
>
>
I'm liking this thread a LOT. However, as a perpetual Ruby amateur (in
both senses - non-professional, and lover), I would like to see the wiki
notion preserved.

If the only author for this material is the programmer(s), that's
needlessly limiting. Some never have time to write up such tutorials,
AND community people have some very good ideas which they would do well
to contribute to the tutorial, over and above the thoughts of the
code-originator. I'd want both sources of input, for the benefit of
people like me (who need all the help they can find).

I sure hope this fine idea sees the light of day.

Tom

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC - Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website)
<< sleightmind.wordpress.com >> (mental health weblog)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Robert Dober wrote:
> 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 had it the other way (Socket::Tutorial etc.) because that would keep
the tutorial in the namespace of the subject. You could structure a
library like this:

module M
   # Give the overall M tutorial here.
   module Tutorial
     # Tutorial for feature x
     def self.feature_x
     end
   end

   def self.feature_x
   end

   # API overview for C
   class C
     # Tutorial for C
     module Tutorial
     end
   end
end

Or maybe it should all be in one global Tutorial space. Dunno...

On Jun 22, 2009, at 09:50, Joel VanderWerf wrote:
> To expand on James's proposal a bit... what about defining a module  
> x::Tutorial, but why shouldn't it?
Why can't the tutorial go on Socket, or Socket.open?  Net::HTTP has
it's tutorials on Net::HTTP...

On Tue, Jun 23, 2009 at 5:00 AM, Joel 
VanderWerf<vjoel@path.berkeley.edu> wrote:
> this:
>  end
>
>  # API overview for C
>  class C
>    # Tutorial for C
>    module Tutorial
>    end
>  end
> end
>
> Or maybe it should all be in one global Tutorial space. Dunno...
Why not Joël, I did not really get it. But I guess it all depends on
the tools and implementors.
The only issue I see is with frozen classes, they could not be reopened 
in a
require 'tutorial/whatver'
right?
But I guess there are no frozen classes in core and stdlib. However it
would be great for third party developers to be able to adopt the
style.

Just my Doller/(42+8)
Cheers
Robert
>
> --
>      vjoel : Joel VanderWerf : path berkeley edu : 510 665 3407
>
>



--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

On Tue, Jun 23, 2009 at 2:51 AM, Tom Cloyd<tomcloyd@comcast.net> wrote:
<snip>
> I'm liking this thread a LOT. However, as a perpetual Ruby amateur (in both
> senses - non-professional, and lover), I would like to see the wiki notion
> preserved.
I would like both ideas preserved and if someone could come up with
more ideas, why not?
Maybe the wiki could take on where the Tutorial stops or be a place to
make the Tutorial evolve too.
Robert
>
>



--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

Eric Hodel wrote:
> Why can't the tutorial go on Socket, or Socket.open?  Net::HTTP has it's 
> tutorials on Net::HTTP...

If every class were so well documented, the subject of this thread
probably wouldn't come up :(

Still, I can imagine wanting 'ri Net::HTTP' to output a short summary of
the api, rather than a full tutorial, which would be accessible by some
other command.

On Jun 23, 2009, at 12:11, Joel VanderWerf wrote:

> Eric Hodel wrote:
>> Why can't the tutorial go on Socket, or Socket.open?  Net::HTTP has  
>> it's tutorials on Net::HTTP...
>
> If every class were so well documented, the subject of this thread  
> probably wouldn't come up :(
>
> Still, I can imagine wanting 'ri Net::HTTP' to output a short  
> summary of the api, rather than a full tutorial, which would be  
> accessible by some other command.

I love Net::HTTP for it's verboseness.  90% of what I want to do is
covered in that page and I can easily see how the whole thing fits
together from all the examples it presents.   This also allow me to
figure out what method I want to look up for the remaining 10%.

On Tue, Jun 23, 2009 at 9:11 PM, Joel 
VanderWerf<vjoel@path.berkeley.edu> wrote:
> command.
Exactly, the purpose of inline documentation is to give a reference
for quick checkup IMHO. I would not like to go through the whole
tutorial everytime. Now one could imagine to have rdoc generate both,
but I feel that this is better done in a different file.
Cheers
Rober
--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

On 23.06.2009 01:20, Robert Dober wrote:
>>  `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

On Tue, Jun 23, 2009 at 11:30 PM, Robert
Klemme<shortcutter@googlemail.com> wrote:
>>> called,
>>> (*) actually, I'm not sure current ri performs a search for x::Tutorial,
> 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.

>> 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?

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.

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

One thought [I think suggested previously?] might be something like

doc/socket_tutorial.rb # a separate file

class Socket
 # a tutorial all about sockets
 module Tutorial; end
 end
end


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."

Another benefit is the tutorials will likely show up in the rdoc's too.

The question for me is still "if you do that, where do tutorials go that 
don't fit [ex: a tutorial about blocks]?" and should it be 
Socket::Tutorial or Tutorial::Socket.  I suppose the former makes it 
more inline and accessible?

Another question is how to preserve a wiki-like feel to the tutorials. 
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?

-=r

On 24.06.2009 00:00, Roger Pack wrote:
> 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
which 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

On Wed, Jun 24, 2009 at 7:40 AM, Robert
Klemme<shortcutter@googlemail.com> wrote:
>>> What'u think?
> reference documentation.  If 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. BTW Thank you Tom
Christiansen for making me discover the wonderful world of closures
(yes he does read this ML but would probably never admit it ;).

That said I agree with you on that rdoc is not that nice a format.
>
>> 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.

No, the tutorials will not go into the code, they would live their lives
Even if RDoc was chosen and there would be a lib/tutorials/string.rb
nobody would ever require that file.
>
>> 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
> which can present a table of contents and is capable of doing full text
> search on it.

I agree with you on this, but it would be better than nothing.
>> 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.

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
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.

Cheers

Robert
--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

>>>> What'u think?
>> reference documentation.  If 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?
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.  Feels 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.


>> 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.

Well rdoc does give us somewhat of a layout in terms of class names.  I 
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.  I 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 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
>> which can present a table of contents and is capable of doing full text
>> search on it.

Good point.  For 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].  Another 
option might be to just flesh that out and call that the tutorial.  Many 
of the things it has are things that could belong in a Ruby 
tutorial--ex: basics of an Array.  Of 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.  The 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.  For some reason that information isn't in the rdocs I'm 
not sure why [1].  I 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?
=r

[1] might be related to this: 
http://rubyforge.org/tracker/index.php?func=detail&aid=26410&group_id=627&atid=2472

On Wed, Jun 24, 2009 at 4:05 PM, Roger Pack<rogerpack2005@gmail.com> 
wrote:
>
> 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.  Feels 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
> Tutorial::Arrays::Chapter_2
>>>
>>> problem.
> integration with existing tools takes out the need for another tool?
> of the things it has are things that could belong in a Ruby
> description.  For some reason that information isn't in the rdocs I'm
> not sure why [1].  I 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?
> =r
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
--
Toutes les grandes personnes ont d’abord été des enfants, mais peu
d’entre elles s’en souviennent.

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

[Antoine de Saint-Exupéry]

> 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].  

I suppose one option would be to put tutorials into said wiki, then add 
a link to them within the rdocs in core.

> I did notice from http://webri.tigerops.org/ that many classes [ex: 
> BigDecimal] already have tutorial like information in the class 
> description.  For some reason that information isn't in the rdocs I'm 
> not sure why [1].  I suppose that means that an option is to put all 
> tutorial information into the class' rdocs...

Example if I go into trunk/ext/bigdecimal and run "rdoc" in that 
directory, shouldn't the generated rdoc's have BigDecimal's description 
somewhere? [they don't seem to, at least with 2.4.3] Is this expected?


> [1] might be related to this: 
> http://rubyforge.org/tracker/index.php?func=detail&aid=26410&group_id=627&atid=2472

So assuming that those tutorials "are there" (and this is a temporary 
bug) this means that some classes have tutorial info already so...to me 
it would seem to make sense that, if you add more tutorial info, you 
want to add it into the rdoc base somehow, so that it can be a sibling 
to the existing tutorials and not split them up.

I think I finally understand Robert's original objection--it is that "if 
it's a tutorial, shouldn't it be basically in some tutorial section 
somehow, not mixed in ad hoc with the rdoc's?"


One way to attempt to not "mix them in together" might be to create the 
tutorials are in a sub folder, i.e. trunk/doc/tutorials, then one can 
generate "tutorial only" rdocs by running rdoc from within that 
subfolder.  It wouldn't (easily) contain backlinks to the class 
description themselves, but it would give you all the tutorials in a 
single rdoc.  Would that help?


The other thought is "if it's not a wiki, it's not user editable".
I'm not sure of an easy way around that one...maybe have a "staging 
wiki" for the tutorials that people can edit, that has a maintainer who 
tracks changes and submits "good ones" to core?

Thoughts?
=r

> One way to attempt to not "mix them in together" might be to create the 
> tutorials are in a sub folder, i.e. trunk/doc/tutorials, then one can 
> generate "tutorial only" rdocs by running rdoc from within that 
> subfolder.  It wouldn't (easily) contain backlinks to the class 
> description themselves, but it would give you all the tutorials in a 
> single rdoc.  Would that help?
> 
> 
> The other thought is "if it's not a wiki, it's not user editable".
> I'm not sure of an easy way around that one...maybe have a "staging 
> wiki" for the tutorials that people can edit, that has a maintainer who 
> tracks changes and submits "good ones" to core?


My latest thought is to "adopt" some wiki or other, and use that wiki 
for staging, then use mechanize to "scrape" it into rdoc style syntax 
which can be rolled into a file to complement the existing rdocs.

like

http://www.meshplex.org/wiki/Ruby/Basic_GUI
or
http://en.wikibooks.org/wiki/Ruby_programming_language
and
http://pleac.sourceforge.net/pleac_ruby/index.html

Thoughts?  I was thinking it might be good to leverage some existing 
tutorials rather than copy and paste them a lot.

Another option would be to create a single rdoc "wiki" page that is user 
editable.

i.e. when you click "edit" you are presented something like ruby source 
[1]

class Socket
 module Tutorial
=begin rdoc
  some rocking tutorial
=end
  def go
  end
 end
end

and are expected to edit it in rdoc style syntax.

I think I may end up doing both, just for fun.  And probably end up 
gemifying it so that I can push out more rapid release/response cycles.

Thoughts?

=r

[1] shameless self-promotion: discovered this syntax via rdoc's rdocs: 
http://allgems.faithpromotingstories.org/gems/doc/rdoc/2.3.0/classes/RDoc.html

On 01.07.2009 14:07, Roger Pack wrote:
>> wiki" for the tutorials that people can edit, that has a maintainer who 
>> tracks changes and submits "good ones" to core?
> 
> 
> My latest thought is to "adopt" some wiki or other, and use that wiki 
> for staging, then use mechanize to "scrape" it into rdoc style syntax 
> which can be rolled into a file to complement the existing rdocs.

My preference would be a web accessible solution and probably a PDF for
printing.  Maybe we could have an editor which signs wiki changes off or
something.

> =end
>   def go
>   end
>  end
> end
> 
> and are expected to edit it in rdoc style syntax.

As you know, I am not a fan of the "code" approach... :-)

Kind regards

  robert

On Wed, Jul 1, 2009 at 4:00 PM, Robert 
Klemme<shortcutter@googlemail.com> wrote:
> My preference would be a web accessible solution and probably a PDF for
> printing.  Maybe we could have an editor which signs wiki changes off or
> something.

Something along the lines of the git community book

http://book.git-scm.com/

--
Rick DeNatale

Blog: http://talklikeaduck.denhaven2.com/
Twitter: http://twitter.com/RickDeNatale
WWR: http://www.workingwithrails.com/person/9021-rick-denatale
LinkedIn: http://www.linkedin.com/in/rickdenatale

> Something along the lines of the git community book
> 
> http://book.git-scm.com/

That book gives you pdf, but doesn't look super easy to edit...

I'm still somewhat leaning to a "wiki where you edit it/read it by 
itself if you like" that can be converted to rdoc syntax if desired. 
Semi-editable rdoc :)

Thoughts?
=r