Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

comment on

( [id://3333]=superdoc: print w/replies, xml ) Need Help??
I've answered this from my perspective as a Perl user/middle-aged-student since it flowed easier on this topic. I've done a fair amount of teaching on other subjects, but thought I'd lay off the theoretical.

  • I hate docs without sample code examples or snippets, or module documentation written mostly for someone above my level of understanding;
  • I love finding code samples on PM that do something differently than I may have thought of (which happens often BTW) ;
  • Also, a code sample may solve my current problem explicitly, but I'll be further along and more willing to dig in to use the module, or whatever, on my own next time. Plus, I study the code to be as sure as I can about why it works the way it does - I have to maintain it after all;
  • Idomatic Perl usage isn't always obviously documented, and learning from senior Perl users always seems like an astounding opportunity for me.;
  • Pointing me to 'the manual' is often not useful to me as I've almost certainly already been through them, but pointing me to other's writeups about the same issues has usually been worth its weight in gold;
  • I dislike being flamed for not having read some write-up or non-official document somewhere that I never found, possibly because it was deep in a cultural abyss I wasn't familiar with. I also dislike posts of some Perl masters that flame (a little or a lot, and there's really only a surprising few in the Perl world who actually do 'flame on' very often) the poster for same, or for non-idiomatic usage not obviously documented, and don't give pointers/links to follow either. My sense is that most Perl users I read online do not have CS degrees, and their (our) depth of understanding is always more shallow than a master's. (Don't get me wrong tho - I've learned a lot from being flamed, and from reading the heat others recieved. I'm just not sure it's a hugely successful educational tool in a public, unfocused forum.)

Thanks for asking about this. That you even thought to ask about it publicly, did so, and will get thoughtful answers here is a perfect example of the PM's value.

The huge variety of answers on PM, as well as the approachability of most Perl documentation, books, FAQ's etc, and the unbelievable helpfulness of Monks is really remarkable.


In reply to Re: Pedagogy: pointers or plaintext posts by tjh
in thread Pedagogy: pointers or plaintext posts by Ovid

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":



  • Are you posting in the right place? Check out Where do I post X? to know for sure.
  • Posts may use any of the Perl Monks Approved HTML tags. Currently these include the following:
    <code> <a> <b> <big> <blockquote> <br /> <dd> <dl> <dt> <em> <font> <h1> <h2> <h3> <h4> <h5> <h6> <hr /> <i> <li> <nbsp> <ol> <p> <small> <strike> <strong> <sub> <sup> <table> <td> <th> <tr> <tt> <u> <ul>
  • Snippets of code should be wrapped in <code> tags not <pre> tags. In fact, <pre> tags should generally be avoided. If they must be used, extreme care should be taken to ensure that their contents do not have long lines (<70 chars), in order to prevent horizontal scrolling (and possible janitor intervention).
  • Want more info? How to link or How to display code and escape characters are good places to start.
Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others contemplating the Monastery: (5)
As of 2024-03-28 20:53 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found