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
···
--
Posted via http://www.ruby-forum.com/\.
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.
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
···
On 01.07.2009 14:07, Roger Pack wrote:
--
remember.guy do |as, often| as.you_can - without end
http://blog.rubybestpractices.com/
Something along the lines of the git community book
http://book.git-scm.com/
···
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.
--
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
···
--
Posted via http://www.ruby-forum.com/\.