Re: A few really humble suggestions

On 7 August 2010 19:50, Meir Guttman <[email protected]> wrote:
<snip>
> May I also offer two suggestions:
> =B7=A0=A0=A0=A0=A0=A0=A0 In examples, pleas use the simplest code possibl=
e. Don't force the
> user to master two other topics before negotiating this one. Please, no
> advanced constructs

I'd tend to agree, up to a point:  the code in SYNOPSIS should be a minimal
usage.

But, for example, nowadays a lot of module authors expect people
who use their modules to use Moose: so even their synopsis documents
will be written assuming a Moosey Perl.  I can understand that this could
be frustrating to newbies (as they will see concepts there that they don't
know), but on the other hand, should the module author really cripple
their synopsis if most of their users will in fact be using Moose anyway?

> =B7=A0=A0=A0=A0=A0=A0=A0 In a MAN page, mandate the inclusion of one more=
 level-1 headings:
> "Notes and Gotchas".

I think that's not a bad idea for a standard heading (along with NAME, SYNO=
PSIS,
DESCRIPTION) but I don't think it's possible (or desirable) to "mandate" an=
y
section - they should emerge, organically, from best-practise.

For both of your comments, I'd suggest that you start trying to make this c=
hange
happen yourself.  I know you said you are a newbie, and that makes you idea=
lly
placed to have useful impact on the documentation:

  * make some patches for a few modules in line with your suggestions
   (try a known "friendly" module author first, for example SHLOMIF
who just responded positively to your suggestions, or I suppose me,
OSFAMERON.)
  * If the friendly authors accept your patches, then try submitting
to others too
  * Once you've got a few POD patches accepted, and have some feedback
from people on whether they are useful, you may be able to get enough
momentum to get things going on a larger scale.

Cheers,
osfameron