[Tutor] Opinion - help could use more examples

[Alan Gauld]

On 19/06/13 18:43, Jim Mooney wrote:
> Here's a peeve of mine about Python help - it often has zero examples.

Remember the help text is being generated from the inline doc strings in 
the code so it depends on what people include in their docstrings.
Also it is intended to be concise because you should only be using it at 
the >>> prompt where you can easily type in your own examples and see 
how it works.

The detailed documentation is (or should be) in the online docs.

> concept. I'm coming from Jquery, which is chock full of examples,

but JQuery doesn't have an interpreter prompt so you can experiment 
easily like Python (I think I may have seen someones implementation
of a test prompt for JQ but I may be hallucinating!)

The Python >>> prompt is not an afterthought, it's been a fundamental 
part of the Python learning/discovery process since day one. It is 
similar in that respect to the workspace in Smalltalk where arbitrary 
bits of code can be evaluated and tested. You are expected to experiment.

> I think the name is confusing zip with compacting, too.

Not sure what you mean by that. It zips two collections together
like a zip fastener. It's got nothing to do with Winzip etc.

-- 
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/