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.

---

---

Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!

Titles consisting of a single word are discouraged, and in most cases are disallowed outright.

Read Where should I post X? if you're not absolutely sure you're posting in the right place.

Please read these before you post! —

• How do I compose an effective node title?
• How do I post a question effectively?
• Markup in the Monastery

Posts may use any of the Perl Monks Approved HTML tags:

a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr

You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)

	For:		Use:
	&		&
	<		&lt;
	>		&gt;
	[		&#91;
	]		&#93;

Link using PerlMonks shortcuts! What shortcuts can I use for linking?

See Writeup Formatting Tips and other pages linked from there for more info.