[Tutor] Opinion - help could use more examples

[Steven D'Aprano]

On 20/06/13 10:21, Devin Jeanpierre wrote:
> On Wed, Jun 19, 2013 at 1:43 PM, Jim Mooney <cybervigilante at 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