On 20/06/13 10:21, Devin Jeanpierre wrote:
On Wed, Jun 19, 2013 at 1:43 PM, Jim Mooney <cybervigila...@gmail.com> wrote:
Here's a peeve of mine about Python help - it often has zero examples.
I printed help(zip) to see what it does and got this:
--snip--
Not understandable right off, IMHO, unless you're already hardcore.
help() is outright harmful to people that don't already know what
they're doing -- it omits things like advice to do with security,
including neglecting to declare that functions are not safe and can
execute arbitrary Python code,
*blink*
The help documentation is not aimed at people who are such utter beginners to
programming that they don't know that calling a function calls the function and
therefore executes code. Documentation always assumes *some* background
knowledge. Even if you start your documentation with:
"The computer is the machine with a screen on your desk. Plug it into the wall
socket, turn the power on, then turn the computer on by pushing the On/Off switch."
it still assumes that the reader knows what a screen is, a desk, the wall
socket, etc. You can't explain *everything*, where would you start?
I think it is perfectly acceptable for the Python documentation to assume that
anyone reading it will understand that calling a function executes code.
--
Steven
_______________________________________________
Tutor maillist - Tutor@python.org
To unsubscribe or change subscription options:
http://mail.python.org/mailman/listinfo/tutor
