Re: Announcing the Perl 5 Documentation Team

On 10-07-02 10:33 AM, Gabor Szabo wrote:
> I don't know much about experts but I think we should make it easy for
> people with no,
> or little background in Perl to get simple answers to their questions
> with pointers to
> further details. I think the vast majority of people using Perl are in
> this category.

When experienced programmers make mistakes it's usually because they 
assume the code is doing one thing when it's doing something else.  For 
example, not remembering that shift does not shift @_ outside a sub. 
Since their confidence in their assumption is very high, they won't look 
up what shift does until it is an act of desperation.  That is, they 
won't do it until they tried everything else they can think of and start 
systematically reading the documentation for everything in the code.

To make things easier, perhaps a sub-section called "Special Cases" 
might be added but if so, then remember that they will skip the rest of 
the documentation and jump straight to it.  That means it must be 
comprehensive (it has to list every special case) though it need not be 
thorough (it can simply say "see above").


-- 
Just my 0.00000002 million dollars worth,
   Shawn

Programming is as much about organization and communication
as it is about coding.

The secret to great software:  Fail early & often.

Eliminate software piracy:  use only FLOSS.