[Tutor] Python Docs (Was: Reformatting phone number)

[Hansen, Mike]

> On Thu, Aug 21, 2008 at 12:01 PM, Dotan Cohen 
> <dotancohen at gmail.com> wrote:
> > 2008/8/21 Kent Johnson <kent37 at tds.net>:
> >> Chapters 2 and 3 of the library reference are highly recommended.
> >> http://docs.python.org/lib/lib.html
> >
> > Let's start from there. I need the startswith() function, 
> but I do not
> > know it's name. I search for "strings" and find this:
> > 4. String Services
> >    * 4.1 string -- Common string operations
> >          o 4.1.3 String functions
> 
> You went too far.  Look at 3.6 (Sequence types) and 3.6.1 (String
> Methods).  Those document operations that work on all types of
> sequences and the methods of the string type.  That's 99% of what
> you'll need to know about python strings.  Kent was pretty specific
> about looking at chapter two and three of the library reference.  Why
> did you start with chapter four instead?
> 
> > But on that page, this is all there is:
> > """
> > The following functions are available to operate on string 
> and Unicode
> > objects. They are not available as string methods.
> ...
> > So Python has only two string functions? That's what it looks like.
> 
> There are only two (non-deprecated) functions in the string module.
> 
> >
> > Thanks, Kent. I will be a nuisance! Is there any place to suggest
> > improvements to the docs? I see on the python.org site it 
> is suggested
> > to email website bugs to the site admin. Does that go for 
> the docs? I
> > am not the one to improve them at this time, as I am unfamiliar with
> > the language, but I could report usability issues such as that
> > mentioned here.
> 
> I believe that doc bugs (and suggestions for improvements) are tracked
> on the python bug tracker (http://bugs.python.org/).  If you're going
> to submit doc patches, you may want to take a look at
> http://docs.python.org/dev/3.0/ which I believe is the beta of the new
> documentation layout for python 3.0.  I'm not sure how much the actual
> contents have changed from the 2.x docs though.  I notice that the
> section on the string module does now refer you back to the methods of
> string and sequences in general, which the current docs do not.
> 
> -- 
> Jerry
> _______________________________________________

I can't put my finger on it, but there's something lacking in the
docs. They are not terrible, but they aren't fantastic either. I'm not
entirely sure what I'd do to fix them. I usually rely on Learning
Python, The Python Standard Library, the Global Module Index section
of the docs, and sometimes Python in a Nutshell. I need to get in the
habit of using help in the shell. Sometimes the docs for a particular
module might be a little obtuse for me especially if it doesn't have
example code. That's where The Python Standard Library book comes in
handy since it has example code. After experimenting in the shell, if
I really get stuck, I'll ask on this list. Maybe having tags or
something to help with searches. On the string methods page, have a
tag called "string functions". I don't think many new to the language
are going to know that they are called "string methods" and not "string
functions". I guess it depends on what language they are coming from
if any at all.

Mike