[Tutor] Opinion - help could use more examples

[Jim Mooney]

On 19 June 2013 16:08, Alan Gauld <alan.gauld at btinternet.com> wrote:

> 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.

True - I have now installed the real html, which is highly visible and
easier, into pyscripter, with hotkeys, and I'll delete that awful chm
help with its tiny font. Now I have Full help for 3.3 and 2.7 a hotkey
away - I can even see 2.7 and 3.3 help side by side in the browser, to
see differences ;')  I have a slow and sometimes intermittent
connection, so I like things installed.

My thought, though, is that since Python is often a first language,
have two-tier help - offer a learner help Lhelp(), that omits the
__garbola__ and uses the space saved for simple examples. With a
proviso on top to go to real help or the docs once you get past the
elementary phase. Just a thought. Or encourage docstring writers that
an example now and then is Not in bad taste ;')

JIm
A pride of lions, a gaggle of geese, a pack of wolves, a sewer of bankers.