A few really humble suggestions
2010-08-07 17:50:58 GMT
Dear doc jockeys!
I joined this mailing list as a frustrated newbie. I have a rather short experience as a Perl user, less than a year and still far from _really_ mastering its art.
During this last year I went over a _lot_ of CPAN, tutorials, PerlMonks and other forums and FAQs. Among these I found some to be really, really excellent and others… well, showing lots of good will.
With this kind of experience, I think that I can be a good test case for newly edited MAN pages and tutorials. I don't think I have to be told the real basics on one hand but in real need of medium and advanced topics.
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 such as eval, (unless of course eval is the subject matter…) Also use _practical_ situations. Looking at some of the examples out there, I have the impression that the intent was more to show-off rather than to show example.
· In a MAN page, mandate the inclusion of one more level-1 headings: "Notes and Gotchas". Side effects to be aware of, common mistakes and misconceptions (this last one will evolve as more feedback is received), special situations, etc.