Perl and the culture of libraries

ruby-talk
21

Peter Hickman wrote:

A critical thing for me is that when programming Perl the POD usually
contains sufficient information and *EXAMPLES OF USAGE* to throw the
basics of an application by simply cutting and pasting from the POD.

Hear, hear. Coming from a Perl background myself, I put a synopsis-like
comment block at the top of every Ruby class or module I write.

I've been surprised at how poor the Ruby language documentation in
general is. Or maybe I haven't found it yet. :wink:

As someone who has no problem writing technical stuff in English, I
wouldn't mind contributing to some sort of open documentation project.
Does such a thing exist for Ruby?

Dave

···

--
Posted via http://www.ruby-forum.com/\.

22

It would be nice to have browseable docs for each project on RubyForge. The gems are there; so it'd be a matter of generating the rdoc in a safe way.

Didn't someone write a rather nice AJAXy gem browser/searcher web app a while back? I can't recall enough about it to Google it up... but it'd be a start, especially if it were hooked into a tab for each RubyForge project.

Yours,

Tom

···

On Aug 6, 2008, at 7:38 AM, Thomas Volkmar Worm wrote:

So to decide, whether the project could be useful to me, I have to
install it and read the generated documentation. So my CPAN for ruby is
'gem server'.

23

And I agree. The trick is, how do we embarrass people into writing that
English? We can't force them to, and we can't simply ignore their library
(how would they know?) -- my favorite idea so far is to drag them into the
cold, harsh light of crowd review, and allow ratings and reviews on
Rubyforge.

Well, you can't force them; this is the *internet*.

But we can provide a good example to follow, and promote other good
examples when we see them.

My 10 cents? A good first step would be to Fix Ruby Garden.

24

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

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"

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.

Your thoughts ?

Peter Fitzgibbons
(847) 687-7646
Email: peter.fitzgibbons@gmail.com
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: pjfitzgibbons@hotmail.com
IM AOL: peter.fitzgibbons@gmail.com

···

On Tue, Aug 5, 2008 at 8:52 AM, Martin DeMello <martindemello@gmail.com>wrote:

On Tue, Aug 5, 2008 at 6:31 AM, Peter Fitzgibbons > <peter.fitzgibbons@gmail.com> wrote:
> Sounds like some changes to rubygems and it's toolset.

Not really. For instance, if I had a small program, doc_init.rb, that
simply spat out a file project-doc.txt that had the following
----------------------------------------------
Project Name:

Authors:

Short Description:

Long Description:

Usage:

Notes:

----------------------------------------------

it would (a) kickstart the documentation process and (b) give other
tools a standard set of headings to look for (c) give authors a
psychological incentive to include those sections in their
documentation (all of which are useful). Once this achieves a critical
mass, we can ask the rubyforge maintainers to consider looking for a
project-doc.txt in projects and make that the landing page. That in
turn will make sure people who submit to rubyforge include such a
file. It just requires a bit of initial buy-in.

martin

25

A critical thing for me is that when programming Perl the POD usually
contains sufficient information and *EXAMPLES OF USAGE* to throw the
basics of an application by simply cutting and pasting from the POD.

I think we should talk to the rubyforge and RAA guys to encourage
"better" behaviour. I am not stating it should be mandatory whatsoever,
but rubyforge really is becoming the "ruby cpan" and it has a huge
influence on various libraries and its shape and thus the overall
ecosystem.

I still think that CPAN as such is overrated. On the other hand I
acknowledge that there will be various bindings or libaries (read
"functionality") which ruby simply does not have yet, and this leads me
to the second proposal.
Rubyforge could make a "porting project". I.e. it focuses on the "most
popular" projects which should be ported. This would be a SIMPLE voting
system and it serves NO OTHER PURPOSE than to see which projects would
be important.

···

--
Posted via http://www.ruby-forum.com/\.

26

Or shut it down, or replace it with some authenticated system. Otherwise, cleaning the spam out of RubyGarden will be a big (and ongoing) job....

Yours,

Tom

···

On Aug 6, 2008, at 11:31 AM, Shadowfirebird wrote:

And I agree. The trick is, how do we embarrass people into writing that
English? We can't force them to, and we can't simply ignore their library
(how would they know?) -- my favorite idea so far is to drag them into the
cold, harsh light of crowd review, and allow ratings and reviews on
Rubyforge.

Well, you can't force them; this is the *internet*.

But we can provide a good example to follow, and promote other good
examples when we see them.

My 10 cents? A good first step would be to Fix Ruby Garden.

27

If they are on a public system, like Rubyforge, and the admins of Rubyforge
(Tom?) decide to include a rating feature, then yes, you've effectively
forced them.

Or, more accurately, they can't force you to stop writing bad reviews.
At that point, they have three options:
- Ignore the reviews (but it's unlikely anyone will want to use their gem)
- Fix their library, so people start giving it good reviews
- Remove their library from the public system (again, reducing their
potential users)

Right now, I have no way of knowing the consensus on a given gem or plugin,
short of word-of-mouth and actually doing the research myself.

···

On Wednesday 06 August 2008 10:31:51 Shadowfirebird wrote:

> And I agree. The trick is, how do we embarrass people into writing that
> English? We can't force them to, and we can't simply ignore their library
> (how would they know?) -- my favorite idea so far is to drag them into the
> cold, harsh light of crowd review, and allow ratings and reviews on
> Rubyforge.

Well, you can't force them; this is the *internet*.

28

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 :slight_smile:
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 :slight_smile:

martin

···

On Tue, Aug 5, 2008 at 7:05 AM, Peter Fitzgibbons <peter.fitzgibbons@gmail.com> wrote:

29

I would say that github seems to have taken a huge bite out of the Rubyforge and RAA circles of influence in a very short time. It also displays the README on the main project master tree page.

James Edward Gray II

···

On Aug 6, 2008, at 6:20 AM, Marc Heiler wrote:

I think we should talk to the rubyforge and RAA guys to encourage
"better" behaviour. I am not stating it should be mandatory whatsoever,
but rubyforge really is becoming the "ruby cpan" and it has a huge
influence on various libraries and its shape and thus the overall
ecosystem.

30

> And I agree. The trick is, how do we embarrass people into writing that
> English? We can't force them to, and we can't simply ignore their library
> (how would they know?) -- my favorite idea so far is to drag them into the
> cold, harsh light of crowd review, and allow ratings and reviews on
> Rubyforge.

Well, you can't force them; this is the *internet*.

If they are on a public system, like Rubyforge, and the admins of Rubyforge
(Tom?) decide to include a rating feature, then yes, you've effectively
forced them.

RubyForge already has an Advogato style rating system for developers,
I can't remember if it's enabled or disabled by default, but it's
optional. I think it *should* be optional, but it does allow people
to rate each other on a few different metrics.

I don't personally take much stock in this sort of thing, and I don't
know that many people even know this system exists on RubyForge, let
alone whether or not they care.

But I don't like the idea of centralizing developer / project review.
I think that if you want to critique a project, that's great, but you
can do it by using the public mailing lists that most projects have,
or by posting a clear description of your complaints on your blog. Or
even better, if you feel like a library is poorly documented, rather
than complaining, document it!

Keep in mind that there are no responsibilities associated with being
a free software developer. Many of us have set high standards for
ourselves and seek to live up to the expectations of others. However,
there is no benefit in forcing this view on others.

Or, more accurately, they can't force you to stop writing bad reviews.
At that point, they have three options:
- Ignore the reviews (but it's unlikely anyone will want to use their gem)
- Fix their library, so people start giving it good reviews
- Remove their library from the public system (again, reducing their
potential users)

Right now, I have no way of knowing the consensus on a given gem or plugin,
short of word-of-mouth and actually doing the research myself.

I find that google blog search and google groups do a fantastic job of
pulling together positive and negative reviews of my projects. I just
need to search for inlinks or keywords and I can easily find what
people think of me. :slight_smile:

-greg

···

On Wed, Aug 6, 2008 at 8:50 PM, David Masover <ninja@slaphack.com> wrote:

On Wednesday 06 August 2008 10:31:51 Shadowfirebird wrote:

--
Technical Blaag at: http://blog.majesticseacreature.com | Non-tech
stuff at: http://metametta.blogspot.com

31

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 :slight_smile:
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 :slight_smile:

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

32

Hi --

I think we should talk to the rubyforge and RAA guys to encourage
"better" behaviour. I am not stating it should be mandatory whatsoever,
but rubyforge really is becoming the "ruby cpan" and it has a huge
influence on various libraries and its shape and thus the overall
ecosystem.

I would say that github seems to have taken a huge bite out of the Rubyforge and RAA circles of influence in a very short time. It also displays the README on the main project master tree page.

It has indeed. I think that at this point, it's unlikely to impossible
that a system or standard is going to emerge that everyone follows, at
least at the granularity of what the section headings in documentation
are called and all that, and probably even at much coarser
granularity. To some extent, having seen a million discussions about
this, I have the feeling that if it were going to happen, it would
have happened by now. Also, since something like github can arise and
change the landscape, simply by being there, I believe it's
fundamentally wrong to look at the whole thing as based on consensus.
We can whip up a bunch of "standards" here and on various wikis, and
that will have nothing to do with how things actually play out.

So the real question, I would say, is: how can the various sites,
philosophies, etc., interact with and connect to each other? I don't
think that cherry-picking CPAN features is all that useful, since it
doesn't address the bigger questions. (To which I have no answer, by
the way. I think it's very possible that there is no set of steps A,
B, ..., n, such that at the end of those steps, there will be any kind
of uniformity or long-term interoperation. I don't even know what step
A would be.)

David

···

On Wed, 6 Aug 2008, James Gray wrote:

On Aug 6, 2008, at 6:20 AM, Marc Heiler wrote:

--
Rails training from David A. Black and Ruby Power and Light:
  * Advancing With Rails August 18-21 Edison, NJ
  * Co-taught by D.A. Black and Erik Kastner
See http://www.rubypal.com for details and updates!

33

Rating *developers* is far less useful in the grand scheme of things.
Rating *projects* on the other hand lets users solve the "searching
for foo returns 20 hits - which one do I want" problem

martin

···

On Wed, Aug 6, 2008 at 6:05 PM, Gregory Brown <gregory.t.brown@gmail.com> wrote:

RubyForge already has an Advogato style rating system for developers,
I can't remember if it's enabled or disabled by default, but it's
optional. I think it *should* be optional, but it does allow people
to rate each other on a few different metrics.

34

There are only 565 rows in the user_ratings table, which I think means most folks seem to feel the same way.

Yours,

Tom

···

On Aug 6, 2008, at 9:05 PM, Gregory Brown wrote:

RubyForge already has an Advogato style rating system for developers,
I can't remember if it's enabled or disabled by default, but it's
optional. I think it *should* be optional, but it does allow people
to rate each other on a few different metrics.

I don't personally take much stock in this sort of thing, and I don't
know that many people even know this system exists on RubyForge, let
alone whether or not they care.

35

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.

[...]

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.

You can't have it both ways :slight_smile: And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn't structured enough to get past the blank canvas effect -
it's a mental effort to decide what to put into it.

martin

···

On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird <shadowfirebird@gmail.com> wrote:

36

Another thread asks:

Where's the wiki that takes you through all
the gotchas and special features of Ruby?

Several years ago, the answer would have been RubyGarden -- perhaps it could be again.

To get some discussion started, would someone in the know describe its current status and prospects?

Are there plans or projects for returning it to a useful resource?

Who are its maintainers and where is it hosted?

What kind of support or assistance would be needed to resolve its problems?

Are there any special issues that make it especially hard to protect the Ruby Garden wiki from spam?

What sort of assistance is needed?

-- Bill Rutiser

37

As the guy who brought up the whole 'secton heading' thing, I wasn't
talking about imposing standards. I was noting that (i) most of the
documentation out there seems to be code-based docs, since that's what
rdoc makes it easy to do, and (ii) that if we made an external
whole-project doc with useful sections easy to do it'd be likelier to
happen.

martin

···

On Wed, Aug 6, 2008 at 7:43 AM, David A. Black <dblack@rubypal.com> wrote:

It has indeed. I think that at this point, it's unlikely to impossible
that a system or standard is going to emerge that everyone follows, at
least at the granularity of what the section headings in documentation
are called and all that, and probably even at much coarser
granularity. To some extent, having seen a million discussions about

38

That's an interesting view and maybe you are right.

I took it more to mean that the current system is less than ideal and all you need to do is produce a significantly better application, which some think github is, to capture some mindshare. I seriously doubt it's likely that a new Perl repository will dethrone the CPAN by comparison.

James Edward Gray II

···

On Aug 6, 2008, at 9:43 AM, David A. Black wrote:

Also, since something like github can arise and
change the landscape, simply by being there, I believe it's
fundamentally wrong to look at the whole thing as based on consensus.

39

GForge doesn't seem to support rating projects AFAIK. Could be done, although folks might value Mercurial support more. I need to do a survey or something.

Yours,

Tom

···

On Aug 6, 2008, at 9:13 PM, Martin DeMello wrote:

On Wed, Aug 6, 2008 at 6:05 PM, Gregory Brown <gregory.t.brown@gmail.com > > wrote:

RubyForge already has an Advogato style rating system for developers,
I can't remember if it's enabled or disabled by default, but it's
optional. I think it *should* be optional, but it does allow people
to rate each other on a few different metrics.

Rating *developers* is far less useful in the grand scheme of things.
Rating *projects* on the other hand lets users solve the "searching
for foo returns 20 hits - which one do I want" problem

40

_Why does a good job of this sort of thing, when he nails the syntax
of, say Hpricot or sqlite in a couple of pages. Really I think that
is the sort of thing that we should be aiming towards.

http://whytheluckystiff.net/articles/aQuickGuideToSQLite.html

···

On Tue, Aug 5, 2008 at 3:54 PM, Martin DeMello <martindemello@gmail.com> wrote:

On Tue, Aug 5, 2008 at 7:43 AM, Shadowfirebird <shadowfirebird@gmail.com> wrote:

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.

[...]

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.

You can't have it both ways :slight_smile: And this is indeed the specific problem
I would like to address - rdoc is too tied into the code, and a readme
file isn't structured enough to get past the blank canvas effect -
it's a mental effort to decide what to put into it.

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