Gavin Sinclair wrote:
On Thursday, March 11, 2004, 12:38:02 AM, jbritt wrote:
Dave Thomas, the creator/maintainer of RDoc, is not (to my knowledge) a
member of the ruby-doc list. You might do well to post to either
ruby-talk or ruby-core.
That's good practical advice for reporting an actual problem, but I
think it's good to run RDoc-related issues by here as well, for a
couple of reasons.
Firstly, more often than not it's a matter of the user not being sure
how to accomplish something. That can be easily corrected here, and
the archives will be the richer for it. Of course the same logic
applies to other lists as well, but this *is* a documentation-related
list.
If Ian's rdoc markup has stopped working because he's using a new
version of Ruby, it's either a bug or a deliberate change in behavior.
I'm guessing it's a bug, in which case the owner of the code should be told.
If it's a case of improper use or a syntax error, then sure, this list
is a reasonable place to track such matters (though I'm not sure if
there are reliable archives anyplace).
Secondly, Dave is very busy, RDoc is a big project, and the lines of
reporting are not always clear (sourceforge?, direct mail?, a mailing
list?).
Everybody on this list is very busy. I've seen Dave respond to RDoc/ri
bug reports on ruby-talk and ruby-core, so I figure they're good
avenues. I tend to prefer public discussions of these things so that
there is a record someplace. (And ruby-talk might be the better choice
because of Google groups archives and searching.)
This list can provide a valuable service by being a first
line of support for RDoc, taking some heat off Dave. Only a little,
but the spread of knowledge is valuable, I think. What do others
think?
In general, community groups help distribute the work load for FAQs, bug
reports, coding quandaries, and so on. I tend to think of ruby-doc as
being focused first on the creation/organization of documentation, and
the development of documentation tools as secondary.
As an aside, I think a great boost for RDoc would be for someone to
take over maintenance (to whatever extent is appropriate). That's my
opinion, not necessarily Dave's. But Dave takes a "show me the patch"
attitude to feature suggestions nowadays, so he obviously welcomes
contributions.
Previous offers to assist with rdoc/ri were met with little enthusiasm.
When Dave has technical concerns or wants input on some design issue he
tends to go to ruby-core, then ruby-talk. (Fortunately, a number of the
ruby-doc folks are also subscribed to ruby-core.)
I'm pretty sure that if anybody in the Ruby community needs help with
something they know how and where to ask, so I wouldn't worry about the
RDoc work load.
James
|
