Re: A few really humble suggestions
Shlomi Fish
It's nice to see a fellow .il'er here.
On Saturday 07 August 2010 20:50:58 Meir Guttman wrote:
> 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.
>
I'm trying to concentrate the best links and resources for Perl beginners
here:
I can also recommend chromatic's Modern Perl book:
http://github.com/chromatic/modern_perl_book
It's not there yet due to its temporary licensing terms and its author
request.
> 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.
>
Nice.
> 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.)
Do you mean string-eval or block-eval?
> 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.
You're right about that.
>
> * 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.
Interesting idea.
Regards,
Shlomi Fish
--
-----------------------------------------------------------------
Shlomi Fish http://www.shlomifish.org/
"Humanity" - Parody of Modern Life - http://shlom.in/humanity
God considered inflicting XSLT as the tenth plague of Egypt, but then
decided against it because he thought it would be too evil.
Please reply to list if it's a mailing list post - http://shlom.in/reply .
Shlomi Fish
first of all I should note that your mailer mis-formats the text portion of
the E-mail message, which makes it harder to read and follow (along with mis
attributions). Please fix it to follow better netiquette.
On Sunday 08 August 2010 10:32:33 Meir Guttman wrote:
> Dear Shlomi,
>
> As a kind of answer to this question of yours:
> > * In examples, please 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.)
>
> > Do you mean string-eval or block-eval?
>
>
>
> I can only say that I gave this "eval" example as _my own_ least understood
> part of Perl. (And I never attempted writing an OO packages, so I am sure
> there are even more complex issues waiting for me. :-(). So the short
> answer to your question is "I didn't know what I meant.!"
Hmmm.... there's a world of difference between string-eval and block-eval. I
explain block eval here:
http://perl-begin.org/tutorials/perl-for-newbies/part4/
What string eval does is evaluate and execute the argument as a Perl
expression, so you can construct code at run-time and run it. It can be
dangerous when done carelessly, but it has some valid (although rare) uses.
Also see:
http://en.wikipedia.org/wiki/Eval
>
>
>
> Thanks again Shlomi! You are a great help for me and I am sure to the rest
> of the community out there too.
You're welcome, and I hope so.
>
>
>
> Meir
Regards,
Shlomi Fish
--
-----------------------------------------------------------------
Shlomi Fish http://www.shlomifish.org/
Why I Love Perl - http://shlom.in/joy-of-perl
Hakim Cassimally
<snip>
> May I also offer two suggestions:
> 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
Caleb Cushing
> If the module doesn't use Moose itself then the documentation should
> assume that the the use of the module will be using Moose
shouldn't*
--
Caleb Cushing
Caleb Cushing
<hakim.ca...@gmail.com> wrote:
> 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?
If the module doesn't use Moose itself then the documentation should
assume that the the use of the module will be using Moose. However I
think if the Module uses moose then it is acceptable to assume that
the consumer of the module will use Moose (since they already have it
loaded an performance is probably the biggest reason not to use
Moose).