perl and the culture of libraries

[Martin DeMello]

http://blog.jrock.us/articles/You are missing the point of Perl.pod

Great article on perl and cpan. I was all ready to say "yeah, ruby has
libraries too - maybe not the tens of thousands cpan has, but i can
usually find what i want" until I read this paragraph:

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.

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.

Some ideas I had:

1. rubyforge should encourage an ecosystem of scripts that works with
it; right now I can't even *find* such scripts other than via "gem
search" (I've filed a suggestion with rubyforge about this).
2. a majority of the projects on rubyforge (mine included, i admit)
have no documentation. on the other hand, the *landing page* of a cpan
project is the documentation. rubyforge's default landing page seems
to contain a lot of information that seems more suited to a sidebar.
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

martin

 

[Peter Fitzgibbons]

[Note: parts of this message were removed to make it a legal post.]

I'm on board.
Where do we start ?

Re-face RubyForge to apply the changes you suggest? Who's maintainer for
RubyForge ?

Peter Fitzgibbons
(847) 687-7646
Email: (e-mail address removed)
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: (e-mail address removed)
IM AOL: (e-mail address removed)

 

[Martin DeMello]

I'm on board.
Where do we start ?

I think a minimally invasive beginning would be a documentation
skeleton generator. Rdoc is wonderful for what it does, but it doesn't
provide much "convention-over-configuration" support for
non-source-code-based documentation, and if Rails has done anything,
it has proven the value of a good set of conventions.

martin

 

[Peter Fitzgibbons]

[Note: parts of this message were removed to make it a legal post.]

Sounds like some changes to rubygems and it's toolset.

Peter Fitzgibbons
(847) 687-7646
Email: (e-mail address removed)
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: (e-mail address removed)
IM AOL: (e-mail address removed)

 

[Martin DeMello]

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

 

[Peter Fitzgibbons]

[Note: parts of this message were removed to make it a legal post.]

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: (e-mail address removed)
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: (e-mail address removed)
IM AOL: (e-mail address removed)

 

[Martin DeMello]

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

 

[Shadowfirebird]

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.

 

[Avdi Grimm]

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.

I've always liked the Perl documentation conventions. Particularly
the fact that *every* CPAN manpage starts with a Synopsis which
demonstrates the essential usage of the library in a few lines of
code.

--
Avdi

Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com

 

[Martin DeMello]

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

 

[Shadowfirebird]

_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

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

 

[Peter Fitzgibbons]

[Note: parts of this message were removed to make it a legal post.]

OTOH, _why is a performance artist, poet, and genius.
A very high bar for us nerdy anti-social shmoes who usually have trouble
coming up with something more creative than "Happy Birthday".

Peter Fitzgibbons
(847) 687-7646
Email: (e-mail address removed)
IM GTalk: peter.fitzgibbons
IM Yahoo: pjfitzgibbons
IM MSN: (e-mail address removed)
IM AOL: (e-mail address removed)

_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

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

 

[Gregory Brown]

OTOH, _why is a performance artist, poet, and genius.
A very high bar for us nerdy anti-social shmoes who usually have trouble
coming up with something more creative than "Happy Birthday".

Nevertheless, that article is utterly devoid of typical _why-isms, it
just demonstrates good technical writing. This is a skill *all*
programmers should have, and it is worth brushing up on as needed. It
sort of goes with the territory, most software is only as good as its
documentation to all but the most inner circles of the technorati.

-greg

 

[brian]

I'm not quite understanding this relationship thing between models and
tables. What I am trying to do within my view is get the price information
by referring to it like this:

<%= @item.itemprice.Qty1 %>

In each of my individual views for the item_master table and the itemprice
table I can get the info directly, but I can't figure out how to access the
price that corresponds to the item.

Here is my item.rhtml view test page:

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

Note: this works

<%= @item.itemDescription %>

This does not

<%= @item.itemprice.Qty1 %>


Below is all my Information:

My Models:


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

item_master.rb

class ItemMaster < ActiveRecord::Base
has_many :itemprices
has_many :item_sub_prices
has_many :item_price_specials
end


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

itemprice.rb


class itemprice < ActiveRecord::Base
belongs_to :item_master
end


My Controllers:

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

item_master_controller.rb

class ItemMasterController < ApplicationController

def show_all
@items = ItemMaster.findall)
end

def item
@item = ItemMaster.find(params[:id])
end
end


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

itemprice_controller.rb


class ItemPriceController < ApplicationController
def show
@price = itemprice.find(params[:id])
end
end

 

[Shadowfirebird]

What he said.


Or, to reduce it to a simple list:

* say what the thing does.
* say why it's such a cool idea to use it.
* walk slowly through one or two examples that demonstrate basic use,
and that use the basic objects and methods.
* Aim to have the whole thing stretch to 2-4 screens of text.

 

[William Rutiser]

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

 

[ara.t.howard]

I've always liked the Perl documentation conventions. Particularly
the fact that *every* CPAN manpage starts with a Synopsis which
demonstrates the essential usage of the library in a few lines of
code.

i have to agree with this. one of the main goals of my main.rb lib
was to be able to enable *every* program to have a '--help' option,
and to allow writing programs that look like this


Main {

description "

stuff about the great program

"


def run
do_stuff
end


}


because a script that does not declare what it does in the first 10
lines is evil and a script that does not have '--help' doubly so.

a @ http://codeforpeople.com/

 

[ara.t.howard]

You can't have it both ways 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

i agreed. pod is good enough without being complicated.

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


a @ http://codeforpeople.com/

 

[ara.t.howard]

Nevertheless, that article is utterly devoid of typical _why-isms, it
just demonstrates good technical writing. This is a skill *all*
programmers should have, and it is worth brushing up on as needed. It
sort of goes with the territory, most software is only as good as its
documentation to all but the most inner circles of the technorati.

i humbly disagree with this. unpack ruby 1.6.8 and look at the docs.
matz isn't a great writer - at least he doesn't spend his time doing
great writing. i don't think it detracts one bit from the ruby
language. it's *ok* to be good at one thing and let others be good at
other things - it's the beauty if open source to a certain degree that
we can all row together to get the project done, docs included.

on the other extreme from ruby are 'ls' and 'grep' - most people have
*never* read the docs for them and yet manage to use them effectively
each day.

software can be good for a variety of reasons: because it's simple
(google) or because it's complex but interesting thereby building an
ecosystem to support itself (rails, facebook). in fact, i'd say that,
to an overwhelmingly large degree, that the most used software in the
world effectively has no documentation, or at least none that anyone
reads... consider email programs, spreadsheet programs, ls, grep,
firefox, and ms-paint... it's fair to say that 99% of the most
popular software is used without requiring any documentation.

i don't think we disagree on this point - rather i think that it's
important to distinguish between 'libraries' and 'applications'
without lumping both into the category of 'software'. in other words
to recognize that documentation needs are different for different
projects. this is part of what makes a one-shoe-fits-all approach
hard i think. it's also why the documentation needs of a rails plugin
are quite different for a developer installing the the plugin vs a
graphic designer doing the same. it's unrealistic to expect the
plugin developer to cater to both.


ps. also worth noting (not to you greg), but for posterity, is that
this thread will consume more energy and words than contributing
documentation to one or two medium sized ruby projects currently just
sitting there in svn or git in all there undocumented glory

pss. http://drawohara.com/post/44678286/eric-hodel-kicks-ass


a @ http://codeforpeople.com/

 

[Gregory Brown]

i humbly disagree with this. unpack ruby 1.6.8 and look at the docs. matz
isn't a great writer - at least he doesn't spend his time doing great
writing. i don't think it detracts one bit from the ruby language. it's
*ok* to be good at one thing and let others be good at other things - it's
the beauty if open source to a certain degree that we can all row together
to get the project done, docs included.

Fair enough, I definitely didn't mean to overgeneralize. But I still
stand by the point that programmers *should* have a decent technical
writing skills. You're absolutely right that when software is
interesting enough, people will contribute documentation. However,
the farther away from the author of the software you go, the more
difficult it is for someone to write about the topic. I'm not talking
about tutorials and walk-throughs here, but API documentation. Eric
Hodel kicks ass for a reason, and that's because he's willing to read
code that he didn't write and document it so others don't have to.
This is something we can appreciate, but not something that should be
expected. (Again, I use 'should' in the sense of 'would be best', not
in the sense of 'absolutely must')

i don't think we disagree on this point - rather i think that it's important
to distinguish between 'libraries' and 'applications' without lumping both
into the category of 'software'. in other words to recognize that
documentation needs are different for different projects. this is part of
what makes a one-shoe-fits-all approach hard i think. it's also why the
documentation needs of a rails plugin are quite different for a developer
installing the the plugin vs a graphic designer doing the same. it's
unrealistic to expect the plugin developer to cater to both.

This is a good point. I definitely overgeneralized by lumping
everything into 'software'. I'm talking about the things that
actually *do* need documentation, such as complicated libraries or
things at that level of complexity.

ps. also worth noting (not to you greg), but for posterity, is that this
thread will consume more energy and words than contributing documentation to
one or two medium sized ruby projects currently just sitting there in svn or
git in all there undocumented glory

Or continuing to document Ruby itself, as much of the standard library
still leaves something to be desired for. (Despite the hard work of
those who've made great progress on this over the last couple years)

-greg