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

[Ricardo Aráoz]

Hansen, Mike wrote:
>> 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.

Python Manuals are pretty good from my POV. You go to "Index" tab and 
type "string", the first entry will get you to the "String Methods" 
page. Just a matter of seconds.
What I find lacking in the docs are a link to a code example for every 
item and a "See Also" link to other related items. With some modules I 
can't make sense of the different bits and pieces till I see a code 
example, and I think this would be the greatest improvement to the 
actually very good docs.