[docs] [issue22691] A Better Help File

James report at bugs.python.org
Thu Oct 23 13:01:38 CEST 2014

James added the comment:

I've written several languages, I'm no novice but, I also know when to brush 
up.Its just how I started, it looks like an opening for others.

-----Original Message----- 
From: R. David Murray
Sent: Wednesday, October 22, 2014 6:25 AM
To: geek.moses at gmail.com
Subject: [issue22691] A Better Help File

R. David Murray added the comment:

The help isn't targeted at teaching you to use the module.  The help is 
targeted at *reminding* you how to use the module after you've read the full 
documentation, which usually does contain examples (though generally not at 
the top of the page...they are usually at the bottom or interspersed...it is 
a *reference* guide after all, the tutorial is a separate thing with yet a 
different target).  I'm afraid, though, that if you find the help to be a 
wall of words, you'll find the library reference worse.  You might be best 
serve by checking out the book/website "Python Module of the Week" 
(pymotw.com), which has a more tutorial style and more examples.

I've never see the Quick Basic style docs.  I don't know if that style would 
be applicable to Python modules.

Bottom line right now, though, is that this isn't really a useful issue for 
the bug tracker.  If you want to discuss strategies for making overall 
improvements in the documentation, that's something that should be done with 
the group of people who focus on documentation.  Their mailing list is 
docs at python.org if you want to join the team and advocate for a change (your 
suggestion has already been posted to that mailing list by the bug tracker, 

nosy: +r.david.murray
resolution:  -> not a bug
stage:  -> resolved
status: open -> closed

Python tracker <report at bugs.python.org>


Python tracker <report at bugs.python.org>

More information about the docs mailing list