ruby suggestion: officially sanctioned tutorials/howto's

[Roger Pack]

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

 

[Robert Klemme]

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.

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.

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

Kind regards

robert

 

[Rick DeNatale]

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

Something along the lines of the git community book

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

--=20
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

 

[Roger Pack]

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