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

Re: Poor State of the Man Pages

Thread Previous | Thread Next
From:
Nicholas Clark
Date:
November 29, 2003 06:58
Subject:
Re: Poor State of the Man Pages
Message ID:
20031129145811.GA23801@plum.flirble.org
I agree with Andy. You have the enthusiasm and the desire to do this -
no-one here is not stopping you starting this project, so please commence.

On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish wrote:

> 1. Collect user stories on what they did not understand in the
> documentation.
> 
> 2. Assign volunteers to remedy these issues.
> 
> 3. Assign volunteers to go over sections of the man pages and try to
> paraphrase them to make them clear enough.

This is not the first thread that you have started where you assume that
there is a pool of volunteer labour that can be tapped into.

Life is not like this.

(I forget what the previous thread was, but at that time I checked my
understanding of Life with my father, who has nothing to do with computer
programming, and he and I are in agreement - in a volunteer organisation
the most precious commodity, the one in shortest supply, is volunteers.
ie people who will actually do stuff, rather than just talking about doing
stuff.)

We (for any perl definition of "we") does not have a pool of volunteer time
that we can lend you for this project. You will have to find your own.

You may not be counting, but there are about a dozen active perl 5
developers on p5p, about half with commit rights. Similarly parrot has
about 5 active committers.

This is the number of competent volunteers that a well established 16-year
old programming language used by many individuals and many organisations
can muster. From the entire world.



On Thu, Nov 27, 2003 at 04:37:41PM +0200, Shlomi Fish wrote:

> And that's it, is bad, because not everyone here knows C-shell or ever has
> to work with it. As for the exec example. One can say:
> 
> 	exec() executes a different program instead of the current perl
> 	program. That is, it will run instead of the script and execution
> 	will never return to the script. (unless in case of error, in
> 	which it is usually recommended to exit immediately).
> 
> That's it! Brief, to the point, and portable for all people. UNIX 101 for
> everybody.

Sure that's good for the introduction.
But I don't want that as the only text in the man pages. The man pages are
meant as a reference, not a tutorial. For reference I want to know what
the errors might be. I want to know that scalar exec uses the shell.
(which has security implications).

Somewhere between I'd want to know that the new program runs as the same
process, and what the rules on inheriting things are (such as open file
descriptors)

> As a general rule, one can expect a beginning Perl programmer to refer to
> the perl*.pod documents looking for a nice information or a trick. I feel
> that they can be made suitable for almost everybody, without sacrificing
> their use for expert hackers.

There seems to be a consensus on perl5-porters that ever more documentation
is good.

Bollocks.

LESS documentation is good. If you can say the same things with less words,
this is much better. The danger we have in increasing the amount of
documentation is given constant programmer time, they read less and less
of it, and are more and more likely to miss the important bits.

I feel that we need to keep the reference separate from the tutorial.
It may well be possible to build them from the same pod source, (

=begin tutorial

=end

=for tutorial

IIRC)


but reference documentation such as man pages doesn't want the tutorial
in it.

On Thu, Nov 27, 2003 at 11:52:36AM -0800, Yitzchak Scott-Thoennes wrote:
> On Thu, Nov 27, 2003 at 11:35:15AM +0200, Shlomi Fish <shlomif@vipe.stud.technion.ac.il> wrote:
> > Once we're through, we release Perl 5.8.3 with all of the changes applied.
> > (or maybe delay it to Perl 5.10.x due to configuration management issues)
> 
> I think you should aim for 5.8.5 (June 2004) at the earliest.  I also
> assume Nicholas will want the changes to go into bleadperl, and then
> be integrated back to maint.

I'm glad that someone is paying attention :-)
Yes and yes.

Also why do documentation changes have to be step changes? Can't most of
this be done incrementally?

On Fri, Nov 28, 2003 at 12:19:47PM +0200, Shlomi Fish wrote:

> I was just posting the idea here to get some feedback. (not one of
> incredibly good S/N ratio evidently, but still)

I thought that the S/N was OK as far as p5p goes.
It just didn't agree with you on some of the points you make.

  Andy:
> > Stop arguing about it and DO IT.  If it's a worthwhile project, people
> > will come on board and make things happen.  If it's not, then they
> > won't.  It's the way open source works.

> Very well, I will.

Good luck.

Nicholas Clark

Thread Previous | Thread Next


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