I've seen some things posted in this thread (overnight for me) that I
mildly disagree with.  So, pardon me while I insert my opinion briefly
without quoting:

1) I'm not convinced that packages and applications need to be treated
differently in this discussion.  The size of the documentation depends
on the complexity of the thing being documented, obviously; but the
way the documentation looks and behaves -- at least to the user --
should probably be the same.

2) I'm not convinced that CPAN does documentation any better than
rubyforge/gem does.  This isn't a matter of having standard fields or
of rewriting our packaging system.  We actually have to get our hands
dirty and write in ... you know ... English.

3) The fact that ls and grep are used by most people without reading
the documentation (assuming that it's true) is not an excuse for ls
and grep not to have documentation.  Go ahead and read the man pages
for ls and grep.  Notice how well they explain how to use the
commands.


On Wed, Aug 6, 2008 at 3:48 AM, David Masover <ninja / slaphack.com> wrote:
> On Tuesday 05 August 2008 07:56:22 Martin DeMello wrote:
> (excerpt quoted from the linked article)
>>    The important thing about Perl is that we have a culture of writing
>> good libraries. No Perl programmer would write a few lines of code,
>> post it to a blog, and call it a "library". Everyone feels obligated
>> to create a CPAN distribution, with documentation (sometimes a bit on
>> the minimal side, but not everyone is a writer), a test suite, a
>> Makefile, etc. I'm not sure why, but this always happens. I think it's
>> because there is a strong convention, and tools that make following
>> the convention easy.
>
> This is somewhat true, and somewhat not. I think the best way to encourage it
> would be to build a public, web-facing index of gems, and evolve some
> community pressure. It could be as simple as a rating system -- actually
> embarrass people for putting up poorly-documented, poorly-tested code.
>
> Some automated tools could help with that, but this is really a social
> project. As you said:
>
>> 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.
>
>
>
> Before I start my rant, I'm going to provide my suggestion. I think this is
> more important than the rant, and I realize some people will get bored.
>
> I suggest that we work on improving the gem system itself. Specifically, we
> need to make it as flexible, powerful, and _easy_ as possible, so that people
> stop developing things like Rails Plugins.
>
> Right away, the biggest feature I miss is reverse dependencies. (Not that CPAN
> had them...) I want to be able to safely install a gem, test it out, and
> remove it, and not have to go hunting in my gems directory for other things
> I'd like to remove.
>
> Second biggest would be virtual dependencies -- only second biggest because I
> don't know if they exist or not. If not, they should. I should be able to
> depend on "any Rack engine", not just Rack itself, and certainly not specific
> things like Mongrel or Thin.
>
>
>
> Now, there is another disturbing thing about Ruby, at least, coming from a
> formerly-Perl perspective:
>
> Perl encourages people to modularize. CPAN packages are (at least, in my
> limited experience) consistently named, and the actual namespace within the
> language generally matches the name of the package on CPAN.
>
> In Ruby, I've mostly seen polar opposites: Either tiny little gems with few
> external dependencies, which will play nice with almost anything -- metaid is
> an extreme example -- or HUGE gems like Rails.
>
> Yes, I realize Rails is broken up into several gems. Well, three of them,
> really -- actionpack, activerecord, and activesupport.
>
> I'm going to argue that activesupport should be at least 10, maybe 20
> different packages -- there are so many little pieces of it that I wish I
> could use for a one-off script, without pulling in the whole library. Things
> like symbol-to-proc, 3.days.ago, etc. But it's going to add significantly to
> the startup time of my script even to require activesupport -- that's bloat.
>
> 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.)
>
> Things like Rack are a refreshing step forward -- but there are very few
> things like Rack.
>
> In Perl, there's an XML namespace, and most XML things are done through
> XML::Parser, which provides a common frontend to several actual XML parsers.
> The actual interfaces to those parsers -- that is, the pure Perl one, the
> LibXML one, and the expat one -- are all separate modules.
>
> Because of this, new things like XML::SAX can be written to fairly easily plug
> into all of those libraries.
>
> In Ruby, well, rfeedparser has its own interfaces to the expat gem, the libxml
> gem (whatever their names are), and its own internal (sloppy) parser, in case
> the others can't be found. Anyone else who just wants to parse XML is going
> to have to do the same thing -- or worse, just pick a library.
>
>
> As long as I'm ranting, may as well talk about plugins. I know about
> gem_plugin -- why isn't it used more? Why, instead, are plugins distributed
> as things tightly-bound to Rails? Suppose I like ActiveRecord, and I need
> has_many_polymorphs -- if I'm in Merb, there's no clear indication of whether
> that will work or not.
>
> Well, that, and plugins are a whole separate (and inferior!) package
> management system that I have to learn, in addition to gems. The one
> advantage I can buy is that you can then distribute your entire, working app
> to a web host who simply has Ruby, no external dependencies required -- but
> you'd still have to freeze Rails to your app to accomplish that. Why not
> freeze other gems, too?
>
> 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.
>
> If you made it this far, thanks for reading. Hope I made some kind of sense.
>
>



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