develooper Front page | perl.perl5.porters | Postings from November 2003

Re: Poor State of the Man Pages

From:
chromatic
Date:
November 28, 2003 12:53
Subject:
Re: Poor State of the Man Pages
Message ID:
1070052662.24069.9.camel@localhost
On Fri, 2003-11-28 at 12:31, Shlomi Fish wrote:

> For example, if I were an employer, I would make sure my company bought a
> copy of it (and other good books) to circulate between the employees.

> As time goes by, the younger generations who became introduced to
> computers in an early age, will be less and less willing to bother getting
> hold of a book just to learn how to hack something. For them, learning to
> hack something is a trial-by-error, write-this-write-that,
> consult-this-and-that, google-here-and-there, etc. procedure. I know,
> because I can tell that that's how I learned a great deal of things, and
> still do to a great extent.

These are both examples of the logical fallacy known as "hasty
generalization".  It is a logical fallacy to argue that everyone (or, at
least, many people) will behave a certain way just because you claim
that you would behave that way in certain circumstances.

Besides that, as Andy pointed out, it's really a waste of time to argue
this.  The best way to get your point across is to produce improved or
new documentation for public review.  If it's useful and accurate and
the pumpking likes it, it'll be accepted into the core.

If not, nothing stops you from putting it up on your own site.

You don't need a big project for this.  You don't need legions of
volunteers, use cases, or a documented workflow process.  You just need
to sit down and do it.  If it's useful, it'll work out.  If not, or if
no one with the time, talent, or desire steps up to help, it won't.

No amount of arguing, berating, or blue-sky dreaming will change this
because this is how it works.

If you do start writing documentation instead of e-mail, one useful idea
floated on p5p recently was a glossary of terms used in the
documentation.  That'd be especially helpful for people who lack a Unix
background that much of the documentation assumes.  It's also a much
smaller job than rewriting Unixy terms out of tens of thousands of pages
of documentation.

-- c




nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About