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

Re: Poor State of the Man Pages

From:
Nick Ing-Simmons
Date:
November 30, 2003 13:28
Subject:
Re: Poor State of the Man Pages
Message ID:
20031130212844.7502.4@llama.ing-simmons.net
Nicholas Clark <nick@ccl4.org> writes:
>
>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.

Also given finite maintainer time, the more docs there are the more
likely they are to "rot" and not track the code changes.
I hold up the many places where aspects of 'open' are now documented 
as an example.

What the commercial books get, that pods do not, is an editor.





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