Shadowfirebird
8/5/2008 2:44:00 PM
I don't wish to be critical (I really don't! That's not just a way of
opening a sentence!) but in my experience there's very little
documentation in Ruby at all. And I'm not convinced that having a
little form with each gem giving the name of the author and a brief
description of what it does is going to help that much. Authors that
want to include that are already finding ways of including it in the
rdoc, usually in some sort of 'readme' entry.
To forestall criticism of my comment:
1) Yes, I'm aware that there are any number of excellent books to buy,
but a FOSS language needs good FOSS documentation.
2) Yes, I'm aware of the pickaxe, obviously. It's a first-class (pun
intended) introduction to the language. And the poignant guide. But
apart from that, where are the websites with tutorials in the
medium-to-advanced level? Where's the wiki that takes you through all
the gotchas and special features of Ruby?* Other languages have them.
3) Yes, I'm aware of rdoc. But I'm sorry, that's not really
documentation. It's just a way of reading the comments without having
to wade through the code. For some people, it's all that is needed.
But for others it's just confusing.
4) Yes, I'm aware I'm feeling very cranky today. Sorry.
I'm really not trying to pick holes in Ruby. I'm just saying that if
you want to document a gem, you need to write a coherent guide
explaining what it does and pointing out the more common options, with
a couple of tutorials. Writing documentation isn't easy, of course,
and worse, it takes different skills to writing code. But, it's not
something that can be skipped.
Shadowfirebird.
* Okay, we know where that last one is: under 10 feet of spam. Still.
On Tue, Aug 5, 2008 at 3:14 PM, Martin DeMello <martindemello@gmail.com> wrote:
> On Tue, Aug 5, 2008 at 7:05 AM, Peter Fitzgibbons
> <peter.fitzgibbons@gmail.com> wrote:
>> Isn't it true, though, that rubygems are the defacto distribution model for
>> projects in RubyForge ?
>> If so, then, like packaging a CPAN .tgz that includes the ./t, ./doc, ./lib
>> and Makefile.pl,
>> the "default" gem hierarchy created/expected by the gem tools should also
>> have ./test, ./doc, and ./lib directories
>
> Yeah, but *expecting* it is a pretty disruptive change. it's hard to
> do it incrementally. having hoe create a structure like that wouldn't
> be a bad idea, though.
>
>> Also, I seem to recall that although many (most?) projects on CPAN include
>> the usual-suspect titles in the documentation
>> (Name, Synopsis, Description...), those titles really are purely cultural,
>> there is nothing in POD spec that declares what the
>> title should be... just "convention"
>
> However, since Perl has settled on said usual-suspect titles, we might
> as well take advantage of their experience and adopt them wholesale :)
> Again, it wouldn't be something that, say, the gemspec enforces - all
> I want to do is provide a tool to make adding those sections the path
> of least resistance.
>
>> A lot of this has to do with the 25yrs of history w/ Perl vs the 12yrs
>> history w/ Ruby. 12 years is a long time... but seems to me
>> a short time in social-cultural development.
>
> Very true. Nothing says we can't stand on the shoulders of the perl
> giants, though :)
>
> martin
>
>
--
All you can do is try to know who your friends are as you head off to
the war / Pick a star on the dark horizon and follow the light