Front page | perl.perl5.porters |
Postings from April 2010
On Mon, Apr 05, 2010 at 01:36:17PM +0200, Raphael Manfredi wrote: > > I think documentation should not be versatile, otherwise newcomers are going > to wonder why one has to use "||" and when "or" is preferable. Seeing both > used in different contexts could even lead people to believe they are fully > interchangeable, at will. Which is not true. There's no defense against people reading something in the documentation that isn't there. It's also important to realize we're talking about the Perl documentation in general. Which isn't written for newcomers. It's written for everyone. Do not dumb down documentation to the level of newcomers - the goal should be that people are newcomers only a short period of their life; they'll spend most of the productive (programmer) life as ex-newcomers. But if you dumb down the documentation, people will stay newbies all their life. AbigailThread Previous | Thread Next