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

Re: Poor State of the Man Pages

Allan Fields
November 27, 2003 16:36
Re: Poor State of the Man Pages
Message ID:
Well, i just passed by this one on the list and couldn't resist...

On Thu, Nov 27, 2003 at 02:43:47PM +0200, Shlomi Fish wrote:
> On Thu, 27 Nov 2003, Alan Burlison wrote:
> > Shlomi Fish wrote:
> >
> > > Are you with me? I volunteer to take the initial effort and get this
> > > effort going. One thing that has to be understood is that the man pages
> > > should be clear, explanatory, and organized. We cannot leave
> > > "transliterate" as such because it's a piece of UNIX jargon and not plain
> > > English. (for example).
> >
> > Looks like English to me:
> >
> >
> It is, but what I meant was its meaning deviates from the meaning we mean
> by the tr/// operator.
> > I'm all in favour of improving documentation, but I would not like to see
> > the documents 'dumbed down'.
> Actually, at the moment, the documentation is quite cryptic and hard to
> understand and people can have problem understanding it even if they
> already know the basis of Perl.
> So, in a way it should be made more clear and idiot-proof. I don't know
> what you mean by "dumbed down" exactly.
> > The online manpages are meant primarily as a
> > reference for people who already know some perl, not as an introductory text
> > - as you have already said there are plenty of good introductory books that
> > already cover this ground.
> >
> Right, _some_ perl. But let's face it: there are many Perl programmers
> nowadays who:
> 1. Are not experienced in any other programming language.
> 2. Are not native speakers of English.
> 3. Have little if any experience with UNIX.
> 4. Just want to find out how to get a job done.
> Now other technologies such as PHP or Python have adapted their
> documentation to accomodate with people who are any of the following four.
> In Perl, the situation is far from being ideal.
> Many times it's not enough to say what a feature does in one clause, but
> it is also necessary to explain it for people who are less knowledgable
> than us, all mighty Perl/UNIX/English/hacking gurus. My friend is one
> example, and I believe many people are considerably worse than him.
> Do we agree?

No, I'm with Alan, please don't dumb down the well written man pages.

They are concise, make good logical sense and have a degree of
perfection just the way they are.

Not that you have a bad idea.  If one must "revise", look only to the
seemingly infinite expanse of free bits.

> Regards,
> 	Shlomi Fish

Allan Fields Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About