[ruby-talk:03296] RE: about documentation

> I want to contribute to the ruby project in my spare time.
> Right now one of the biggest needs appears to be English
> documentation.  

Me too x 2.

> limitation was from the fact that perl documentation was handled by
> Tom Christenson and he felt that the Perl books where a better source
> for a reference manual.

And here's what I would like to say to you:

1) let's not rush
2) let's look what Dave&Andy have to offer to us
3) let's try to do this a little bit coordinatedly.

With first I mean that it's easy to do something what have no use at all. So
let's analyze the situation first.

The second means that we probably don't have any need to do library
reference, if everything goes right. We might better to do it anyway, so
let's wait for few months, maybe to the autumn, and let's make decisions
then.

And with the third one I hope we're not duplicating the work load, we'll
have one set of beautiful and comprehensive documentation done in "the right
way" as much as possible.

I, for one, have some doubts the rdtool is the way to go. I might make an
overkill suggestion, but I feel we should be heading into XML-world and
maybe make a converter to rd-notation. This said, I've not looked rdtool
carefully, so I might be way off here.

I've told I'm available to work volunteering. In
http://blade.nagaokaut.ac.jp/cgi-bin/scat.rb/ruby/ruby-talk/2759 matz
volunteered to set up the infrastructure for it (maybe he has done that
already :).

So based on your enthusiasm, I guess you could act as a head of the Ruby
documentation project. I think these things should be talked before somebody
really does the job. That way, I hope, we could navigate in the right
direction to get good, free on-line (and print ready:) documentation.
There's always room for the target of Christiansen's opinion: real books!

Maybe we could start by discussing the need, the depth and the priority for
topics to be documented. Simultaneously we could talk needed 

infrastructure:
- freely editable XML, patches going though the documentation maintainer,
ending up the CVS-tree

the technology:
- XML (maybe look to TEI-might help)
- Ruby scripts handling XML2RDtool, XML2HTML (maybe using internal/external
XSLT), XML2Latex, XML2PDF (maybe XSL-FO?)

collaboration tools:
- CVS, web page, mailing list, Wiki, newsgroups 
- enabling coordinated assignments and reassignments :)

Do not let this look overkill. These are just random ideas.

	- Aleksi