On 09/09/2018 03:12 PM, Peter Scott wrote:
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."
Hi Peter,
I though I made the clear with my "dictionary" explanation. Oh well.
My technical writing is a work in progress. The best technical writer
make it look easy, but is definitely a skill!
Perl 5 has "perldoc". For instance:
$ perldoc -f say
say FILEHANDLE LIST
say FILEHANDLE
say LIST
say Just like "print", but implicitly appends a newline.
"say LIST" is simply an abbreviation for
"{ local $\ = "\n"; print LIST }". To use FILEHANDLE
without a LIST to print the contents of $_ to
it, you must use a bareword filehandle like "FH",
not an indirect one like $fh.
"say" is available only if the "say" feature is
enabled or if it is prefixed with "CORE::". The
"say" feature is enabled automatically with a
"use v5.10" (or higher) declaration in the
current scope.
Pretty much everything you need to know about "say" in a nutshell.
Perldoc is very thorough. I only sometimes have to ask for help.
With Perl6's docs, I ALWAYS have to ask for help.
On the other hand. I find the CLI format of perldoc to be really
cumbersome. I go on-line and look it up on PerlDoc web page.
I hope Perl6 does not go in the perl 5 CLI perldoc direction.
As for my part in all of this, I will start using JJ suggestion and
start taking out bug reports when I get gobsmacked by a incomplete
explanation in the docs. This is all part of "Kaisen" (constant
improvement), which open source excels so much at. I am
the perfect person for this as I usually am starting from scratch.
I just can't make a go of programming tutorials. I have to actually
go and program something I or a customer need(s). I can't
get past
print "Hello World\n";
It does not help that I am not new to programming. When I see
the "print" lesson, after I wake up and if I remember what I
saw, I immediately want to know how to write in color, bold,
the the standard error, formatted real numbers, etc.. Add
to that how to read from the stdin and stderr.
In other words, if you manager to get my attention, it is
difficult to keep me on target as my mind wanders off to
what I actually need. And the technique (Microsoft) of
using 100 words where 10 will do, drives me nuts.
I also LOVE examples. Sometimes an example will get past the
fog quicker than anything else. And you will notice in a
(spoken) language dictionary, they ALWAYS give
an example of how to use a work in its various contexts.
I admire your ability to write books on technical subjects.
It is definitely a skill that takes a lot of work! I
definitely can't do it.
-T
