perl and the culture of libraries

[Shadowfirebird]

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.

 

[Martin DeMello]

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

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

 

[Martin DeMello]

i agreed. pod is good enough without being complicated.

has everyone forgotten about rdtool? we *have* pod for ruby now.

I had indeed!! Thanks for the reminder.

martin

 

[Tom Copeland]

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.

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

 

[Gregory Brown]

There's no need to replace.

Prawn:DF::Writer

Then a user can

include Prawn

That's a solid practice.

Except for the fact that I'm the current maintainer of PDF::Writer and
I don't want to continue to maintain a library that should be retired
as soon as possible.

Creating confusion by layering an additional namespace on things is
not what I call a solid practice :-/

Instead, I'll just wait as long as it takes where people support the jump.

-greg

 

[James Gray]

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.

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

 

[David A. Black]

Hi --

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.

That's really what I mean by "something like github": a system that
some percentage of people like and therefore decide to use.


David

 

[David Masover]

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.

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.

 

[Gregory Brown]

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.

-greg

 

[Martin DeMello]

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

martin

 

[Tom Copeland]

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.

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

Yours,

Tom

 

[Tom Copeland]

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

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

 

[Daniel Berger]

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.

There was gemtacular.com, but it appears to be dead. Anyone know what
happened?

It might be nice to have some sort of rating on the RF page.

Regards,

Dan

 

[Trans]

I agree with Advi and Martin that the landing page of a project is
important. The CPAN authors' documentation quality improved because of
CPAN, not the other way around. Rubyforge would lead to better Ruby
libraries if it looked less like Sourceforge and more like the module
pages athttp://search.cpan.org. This is not to knock Rubyforge; it
filled a community need. But I think the community deserves more now.

On that note, let's look at a sample distribution page (http://
search.cpan.org/~abw/Template-Toolkit-2.19/). For those unfamiliar
with CPAN, a distribution is sort of the "top level"; it can contain
many modules. CPAN is a lot more than well-documented modules. There
are ratings and reviews, which can help when your searches bring up
multiple modules that do the same thing. I find it useful for
identifying abandon-ware: sometimes you'll see in a review that the
module has been superceded by another. There is also a gaggle of
volunteers who test Perl modules on various platforms. This is
invaluable if you are using a non-mainstream environment (e.g. cygwin)
or if the module has C extensions. And it's fairly automated; there's
a CPAN module called Test::Reporter and a special version of CPAN
(CPANPLUS) that can automatically download a module, run its test
suite, and report results. You can also find dependencies prior
versions. Like Rubyforge, there are discussions and bug reporting that
are sometimes used, sometimes not.

Module authors tend to use Module::Starter which is just like hoe, in
that it generates a nice module skeleton, ready to submit to CPAN.
Another thing I noticed about module authors is that they tend to use
more pragmatic, namespaced module names, i.e. they would tend to use a
name like "PDF::Simple" instead of "prawn". Though this may be due to
the fact that 14,000 modules require a bit more organization and
findability.

While there is no hard standard for Ruby, the general convention for
namepaces is the opposite of Perl.

In Perl for instance you might find "PDF::EasyPDF" or "PDF::API2". It
is the second (or last) part of the namespace that makes it unique.
This leads to many project names having more technical names (eg.
API2), rather than colorful names.

In the Ruby world the general convention has moved in the opposite
order. With the unique name coming before the technical
classification. Eg. RedCloth::TextileDoc, or LibXML::XML:ocument.

The reason for the difference stems from the fact that Perl
development is organized around CPAN, which is organized by module
namespace, whereas Ruby development is much more decentralized and the
main organizing factor is RubyGems with organizes us by project names.
I also suspect this difference arises in no small part to the fact
that Ruby file names do not have to match our module names (though it
can be a helpful practice to do so).

We can of course argue about which is better. Some Ruby developers
have taken to trying the Perl way, but b/c of the decentralized nature
of Ruby development, name clashes in these cases are not uncommon. I
find the Ruby convention preferable, since it allows for more easily
including modules into my own for convenience. Eg.

module MyApp
include LibXML
doc =3D XML:ocument.new
...
end

T.

 

[Shadowfirebird]

Is there anything we can do on RubyForge to encourage people with
documentation-writing skills to contribute, and to match them up with
projects that need documentation?

 

[Martin DeMello]

Is there anything we can do on RubyForge to encourage people with
documentation-writing skills to contribute, and to match them up with
projects that need documentation?

Some sort of coverage report would be neat. This (yet again) gets back
to my idea of having a few standardised documentation sections as a
baseline - there's a quick, automated way to report which projects are
missing which sections. Once that was done, people could scan the
list, find a missing section they felt like contributing, and do so.

A complicating factor is that on CPAN one project corresponds to one
module/program, whereas on rubyforge there are often multiple packages
under the umbrella of a single project.

martin

 

[Gavin Sinclair]

He's right - there really is nothing in the ruby culture/toolset that
encourages everything shared to be *properly* shared. Hoe and friends
[http://nubyonrails.com/articles/tutorial-publishing-rubygems-with-hoe]
are a great step forward, but their use doesn't seem to be widespread
yet. At the very least, an interesting thing to ponder.

That's (partly) because Rubygems makes it so easy to "release" small
"libraries" (really naescent bundles of code that may or may not prove
useful). The benefit is that there's more code out there; the problem
is it dilutes the ecosystem. Not all gems are equally deserving of
the effort required to release them *properly*. Accordingly, the gem
tool should not treat all gems equally as it does now.

On Rubyforge there's a good piece of metadata: the status of the
project (rated 1-5 with associated descriptions like "Beta" and stuff
-- going from distant memory here). I think the ecosystem would
benefit if gems had something like this built in, and maybe a free-
text description of the status, like "Small but useful library; not
really documented yet." These things would help users sift through
the mass of gems, and enable us to get the benefit of an active
ecosystem without the problems of dilution.

Some ideas I had: [...]

3. perhaps rubygems could support commands like "gem readme", "gem
changelog", "gem todo" and "gem examples" to encourage people to fill
in such documentation where appropriate

Excellent. I proposed the same thing (well, the "readme" part,
anyway) on the Rubygems list a long time ago. It didn't get any
support. Now that the platform has proven itself and there are
thousands of gems, surely it's time to consider this and other related
ideas.

A related suggestion I had back then was a second command "gemx" that
would allow other useful (perhaps experimental) commands without
polluting the "gem" command namespace.

Gavin

 

[brabuhr]

And ActiveRecord -- why, exactly, is validation included? Why not make it a
mixin? That way, with duck typing, I could pull at least some of the default
Rails validations into another ORM. (validates_uniqueness_of might even work,
if the #find methods are similar.)

There is an experimental project to pull parts of ActiveRecord (e.g.
validations)
into external mixins that can be shared with other model layers:

http://dev.rubyonrails.org/svn/rails/tags/rel_2-0-1/activemodel/README

"Also note that because this module MUST be able to stand alone (for
use in presenters etc), it does not COMPLETELY supplant
ActiveRecord::Validations. AR-specific stuff like
the n=>:save|:update|:create option, as well as
validates_uniqueness_of are taken care of by AR:V, albeit by extending
AM:V"
http://www.ruby-forum.com/topic/158973

Here's a crazy idea (not sarcasm; I realize it's quite possibly insane): When
you build a framework like Rails, designed to aid in rapid development of an
app, design it around building components, not whole applications. That is,
design it around building gems -- possibly lots of tiny gems (would one per
model be too much?) -- so that when it comes time to "extract functionality"
from your app, you'll already know what depends on what, and what you'll need
to disentangle.

There have been some forays into leveraging more advantage of gems in rails:

http://revolutiononrails.blogspot.com/2007/01/gem-based-development-process.html
http://ryandaigle.com/articles/2008/4/1/what-s-new-in-edge-rails-gem-dependencies
http://www.intridea.com/2008/6/11/gemplugins-a-brief-introduction-to-the-future-of-rails-plugins

 

[David Masover]

There have been some forays into leveraging more advantage of gems in rails:

"Gem-based development" sounds very close to what I meant -- but there doesn't
seem to be much mention of how one might go about this as a _process_, only a
few tools that might be useful.

Gem dependencies are nice, but all that does is encourage the use of gems
rather than rolling your own functionality. I don't think this was ever a
problem -- do people actually roll their own HTML parsers to use with Rails?
At least the people I work with seem to be smart enough to use things like
hpricot, or rfeedparser.

Gem plugins is a step in the right direction -- but it's still not
particularly easy, compared to simply developing a plugin as an SVN external
(or with piston) -- or simply adding another model to your existing app.

And if you look at the name, it seems very much like "gem plugins" are simply
an approach to making plugins easier. It's still an approach of plugging
something into an existing app.

I'm not sure what is needed, technologically, to make this happen -- maybe
it's simply better scaffolding -- but I'm thinking that about the only thing
that should be in the application is the routing. Everything else could be
split off into re-usable components -- and at a fine granularity.

Of course, that's my opinion, and it runs directly contrary to the 37signals
approach, which seems to be: Develop a monolithic app first, and don't
abstract anything until you've repeated it at least three times. Re-usable
components, in that model, are created by extracting them from an existing
app.