> On Sep 9, 2018, at 2:50 PM, ToddAndMargo <toddandma...@zoho.com> wrote: > > My point is that the dictionary should teach you how to use > the word in question. I do believe I am correct in my > assertion too.
Let's be clear that reference documentation is not the same as a tutorial. This is the difference between the Camel and the Llama. Absolutely, programmers need both of these, but at different times. When you are in programming mode as opposed to learning mode, and you want a definitive, authoritative, complete answer to a specific question, you need reference documentation that is not encumbered by pedagogical devices, interstitial examples, or simplifying assumptions. Open source projects frequently shoot themselves in the foot by assuming that they can improve any documentation simply by adding whatever people are asking for to the same buckets. Perl 5 got this right (at least, initially) by creating the ---tut series of pods. Good programmers are not always good writers or teachers. Peter Scott Author, "Perl Debugged," "Perl Medic," and "Perl Fundamentals."
