Front page | perl.perl5.porters |
Postings from April 2010
On Sat, Apr 10, 2010 at 17:05, Abigail <abigail@abigail.be> wrote:
> 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.
Or alternatively they'll spend a few minutes trying to grok our
documentation, give up and move onto Ruby or Python.
I know Perl the best of the three but I find it a lot easier to skim
Python's and Ruby's documentation than ours. Their documentation tends
to be focused on short & to the point examples which are syntax
highlighted and show the result of evaluating every expression, for
example:
Python: http://docs.python.org/tutorial/introduction.html#numbers
Ruby: http://pine.fm/LearnToProgram/?Chapter=07
Perl: http://perldoc.perl.org/perldsc.html
That's documentation linked from our Tutorial section
(http://perldoc.perl.org/perl.html#Tutorials). I find that ours
compared to theirs is too long, harder to read and not to the point.
Why is a DEBUGGING section in perldsc mainly about some quaint bug in
perl 5.002 for instance?
Consistency and attention to detail like that goes a long way. It also
helps newbies and experienced programmers alike. I happen to know Perl
very well in that there's very few things you could throw at me that I
genuinely wouldn't understand, except maybe the format syntax. I still
like Python and Ruby's documentation better, and find it easier to
skim it for answers when I've forgotten something.
Ours generally:
* Isn't very topographic. It's very easy to find the *one* place in
Python's docs that discusses feature X in detail. With Perl's docs I
generally have to look in a lot of places.
* Is very inconsistent: I can't look at one "conventions used in
this manual" that says something like "Every time we show an
expression we'll also show you the evaluation result below as '==>
result'". If I copy/paste 10 examples from the manual I'll probably
get 5 different coding styles and 3 examples that don't compile under
strict.
When Jari Aalto originally joined #p5p (before all these threads) and
wanted to patch perlfaq* so that it didn't use brian d foy's odd
indenting style I suggested instead that he should contact the
maintainer of http://perldoc.perl.org/, and get them to to pipe their
code examples through perltidy with some sane setting. Precisely
because bikeshedding (of which we have now several threads) is likely
to be the result while some of the big issues in our POD are
neglected.
Thread Previous
|
Thread Next