On 7 August 2010 19:50, Meir Guttman <m...@guttman.co.il> wrote: <snip> > May I also offer two suggestions: > · In examples, pleas use the simplest code possible. 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? > · 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, SYNOPSIS, DESCRIPTION) but I don't think it's possible (or desirable) to "mandate" any section - they should emerge, organically, from best-practise. For both of your comments, I'd suggest that you start trying to make this change happen yourself. I know you said you are a newbie, and that makes you ideally 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
