Documentation suggestions

[Rhamphoryncus]

Here are some thoughts on reorganizing Python's documentation, with
one big suggestion.

Throwing in my own 2¢.. I think the language reference should be
disseminated into the rest of the documentation. Some of the stuff
(operator precedence anybody?) could be done directly, while more
technical aspects could be put in boxes with green[0] backgrounds
saying "technical details". Thinks specific to one implementation
could further be given a blue[0] background.

I don't expect everything to make the transition. Are discussions of
"atoms" and fragments of BNF really better than calling them
expressions and linking to CPython's Grammar file?

 

[Steve Holden]

You are correct about the tutorial. Just try to look at the home page
through the eyes of a curious Windows user who wants to learn
programming and is trying to decide whether to take up Perl, Ruby,
Python, or Visual Basic, let's say.

On the home page, the first link that catches the eye for this user is:
"Beginner's Guide to Programming - <bold> start here if you're new to
programming </bold>." That's me. Click.

Now you are on a page with promising-looking links that all start with
"BeginnersGuide," but the first three are not warm welcomes, they are
housekeeping matters about where you can take courses or how to
download Python for people who don't know whether they want to or not
yet, or there's one that says "examples" which will take you to the
ActiveState Cookbook site so you can get really confused.

Then you hit the link that says "BeginnersGuide/Nonprogrammers" Ah!
That's me. <click>

The first prominent link says: "Python Tutorial" along with a notice at
the top of the page that tells you if you've never programmed before
this is the page for you.

Click on Python Tutorial. Some official business to start off. Then you
see, "Whetting Your Appetite" Ah, I am ready for that. <click>

The first sentence reads:

"If you ever wrote a large shell script, you probably know this
feeling: you'd love to add yet another feature, but it's already so
slow, and so big, and so complicated; or the feature involves a system
call or other function that is only accessible from C ...Usually the
problem at hand isn't serious enough to warrant rewriting the script in
C; perhaps the problem requires variable-length strings or other data
types (like sorted lists of file names) that are easy in the shell but
lots of work to implement in C, or perhaps you're not sufficiently
familiar with C."

Most of the site has been laid out by programmers, for programmers, who
apparently want to keep it that way, based upon what I've seen.

I think the Python community as a whole should take this on board as
fair criticism. It would be really nice if a total beginner did actually
see a usable path through the web to their first working Python program.

regards
Steve

 

[skip]

Adam> I don't expect everything to make the transition. Are discussions
Adam> of "atoms" and fragments of BNF really better than calling them
Adam> expressions and linking to CPython's Grammar file?

Actually, yes. The actual Grammar file isn't designed for explanation
(mostly it's more complex, but it also has extra productions) and is
somewhat (maybe a lot) different than the BNF in the ref manual.

Skip

 

[Iain King]

The library reference has so many modules that the table of contents

is very large. Again, not really a problem that we can fix; splitting
it up into separate manuals doesn't seem like it would help.

I like the Global Module Index in general - it allows quick access to
exactly what I want.
I would like a minor change to it though - stop words starting with a
given letter rolling over to another column (for example, os.path is at
the foot of one column, while ossaudiodev is at the head of the next),
and provide links to each initial letter at the top of the page.

Iain

 

[skip]

Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.

I know it's not what you asked for, but give

http://staging.musi-cal.com/modindex/

a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.

Skip

 

[Iain King]

Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.

I know it's not what you asked for, but give

http://staging.musi-cal.com/modindex/

a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.

Skip

Well, the point of the GMI is to lookup whatever module you are
currently having to use for the first time (at least it is for me).
Giving easy access to the modules I've already had to look up (because
they are common) doesn't really help - I've already accessed those.
It'll be nice when I have to find some obscure feature I haven't used
in them before, but really, all I'd like is an easy to use index

Iain

 

[Adam Olsen]

Adam> I don't expect everything to make the transition. Are discussions
Adam> of "atoms" and fragments of BNF really better than calling them
Adam> expressions and linking to CPython's Grammar file?

Actually, yes. The actual Grammar file isn't designed for explanation
(mostly it's more complex, but it also has extra productions) and is
somewhat (maybe a lot) different than the BNF in the ref manual.

IMO the only people who are going to appreciate BNF used for
explanation are those working on language implementations, and they'll
need to understand the Grammar file anyway. The rest of us need a
simpler explanation involving examples.

Having a large and detailed language specification, although an
admirable ideal, is a waste of time when the target audience is
perhaps a few dozen people. Make it useful for everybody and it'll be
worth maintaining.

 

[skip]

Iain> Well, the point of the GMI is to lookup whatever module you are
Iain> currently having to use for the first time (at least it is for
Iain> me). Giving easy access to the modules I've already had to look
Iain> up (because they are common) doesn't really help - I've already
Iain> accessed those. It'll be nice when I have to find some obscure
Iain> feature I haven't used in them before, but really, all I'd like is
Iain> an easy to use index

Reorganizing the global module index isn't all that straightforward. It is
generated by latex2html. To change its layout would probaly require some
additional markup and mods to latex2html (not a pretty piece of code as I
understand it).

OTOH, I find myself returning to the same module docs over and over again to
look up function arguments, regular expression syntax, that sort of thing.
Having to page down past dozens and dozens of modules I don't care about to
click on "sys" or "datetime" motivated me to write my little hack.

Skip

 

[skip]

Adam> Having a large and detailed language specification, although an
Adam> admirable ideal, is a waste of time when the target audience is
Adam> perhaps a few dozen people.

Just because that audience is small doesn't mean they are unimportant.
There are currently four actively maintained/developed implementations of
Python. A common language reference manual is important for them, and
indirectly for the people who use the four implementations.

I'm not trying to discount the value of a good Users Guide.

Skip

 

[Iain King]

Iain> Well, the point of the GMI is to lookup whatever module you are
Iain> currently having to use for the first time (at least it is for
Iain> me). Giving easy access to the modules I've already had to look
Iain> up (because they are common) doesn't really help - I've already
Iain> accessed those. It'll be nice when I have to find some obscure
Iain> feature I haven't used in them before, but really, all I'd like is
Iain> an easy to use index

Reorganizing the global module index isn't all that straightforward. It is
generated by latex2html. To change its layout would probaly require some
additional markup and mods to latex2html (not a pretty piece of code as I
understand it).

OTOH, I find myself returning to the same module docs over and over again to
look up function arguments, regular expression syntax, that sort of thing.
Having to page down past dozens and dozens of modules I don't care about to
click on "sys" or "datetime" motivated me to write my little hack.

Skip

Argh, you made me look at the html again - at least now I know *why* it
is so disgusting. I understand there's a new version coming out soon,
hopefully in html 4 strict or xhtml. I'm sure at that point it'll be
easier to use. I can wait.

Iain

 

[Adam Olsen]

Adam> Having a large and detailed language specification, although an
Adam> admirable ideal, is a waste of time when the target audience is
Adam> perhaps a few dozen people.

Just because that audience is small doesn't mean they are unimportant.
There are currently four actively maintained/developed implementations of
Python. A common language reference manual is important for them, and
indirectly for the people who use the four implementations.

What I meant is that a small audience is not going to draw enough
attention to get the effort it requires. I agree absolutely that the
material it contains is important. That's why I feel it should be
merged with the other documents, to ensure that it really does get
maintained.

 

[Steven Bethard]

Iain> I like the Global Module Index in general - it allows quick access
Iain> to exactly what I want. I would like a minor change to it though
Iain> - stop words starting with a given letter rolling over to another
Iain> column (for example, os.path is at the foot of one column, while
Iain> ossaudiodev is at the head of the next), and provide links to each
Iain> initial letter at the top of the page.

I know it's not what you asked for, but give

http://staging.musi-cal.com/modindex/

a try. See if by dynamically migrating the most frequently requested
modules to the front of the section it becomes more manageable.

That's pretty cool. What I don't know is how it would look after
thousands of people using it. I know that I probably only have 10
modules or so that I consistently need to check the docs for. Your hack
above would conveniently place those all at the top if I was the only
user. But are those 10 modules the same 10 modules that other folks
need? I don't know...

Of course, the only way to find out is to try...

STeVe

 

[Rocco Moretti]

There's another struggle within the LibRef: is it a reference or a
tutorial? Does it list methods in alphabetical order so you can look
them up, or does it list them in a pedagogically useful order? I
think it has to be a reference; if each section were to be a tutorial,
the manual would be huge. Here I think the solution is to encourage
separate tutorials and HOWTOs, and link to them from the LibRef.

I actually like the conversational, tutorial style the current LibRef
has -- in fact I consider that style one of the Python Docs strengths.

All too often I see manuals that consist of only fuction by fuction &
class by class breakdowns. That's fine if the module is just a
collection of independant functions, but falls short whenever you want
to use multiple functions & classes in a module together. Function by
function documentation tends to ignore the "big picture," how all the
functions & classes work together, and the philosophy behind their use.
*That's* what I feel it is important to document - if I want to know
parameters, return values and side-effects, I'll just look at the doc
strings.

Certainly you could go for the User Manual/Reference Manual dichotomy,
but in my experience, the User Manual tends to get short shrift - the
experts writing it tend to think that it's just for "n00bs", and leave
out the complex and esoteric items, thinking that the Reference Manual
suffices. Unfortunately, the background and philosophy are needed *more*
for the complex/esoteric functions than for the simple ones, merely
because you're less likely to understand them from a "takes a,b,c, sets
the froz flag, and returns x,y,z" type description.

And to expand on what Michael Spencer said, a lot of the time when I'm
digging throught the LibRef, I'm looking for a module that'll help me do
'X'. Most of the "Reference Manuals" I've seen tend to assume you know
what fuction you're looking for, and don't give you any direction in the
forest of function descriptions. With the current tone/level and
categorical grouping of the LibRef, it's easy to browse through and look
for things that might help (at least easier than it would be with, say,
a strict alphabetical list).

 

[Aahz]

OTOH, I find myself returning to the same module docs over and over
again to look up function arguments, regular expression syntax, that
sort of thing. Having to page down past dozens and dozens of modules I
don't care about to click on "sys" or "datetime" motivated me to write
my little hack.

That's why I use Lynx! ;-) ("/]re" takes me right to regex docs)

 

[Kent Johnson]

I think the Python community as a whole should take this on board as
fair criticism. It would be really nice if a total beginner did actually
see a usable path through the web to their first working Python program.

OK I'll bite. That Beginners Guide page has bugged me for a long time.
It's a wiki page but it is marked as immutable so I can't change it.
Here are some immediate suggestions:

- get rid of the 1-7 list at the top it is very confusing and does not
present information in a useful form or order. All of these links except
the help link appear in the body text in more useful form.

- Change the sentence "Read BeginnersGuide/Overview to learn the key
points." to "Read BeginnersGuide/Overview to learn what makes Python
special." Or maybe get rid of it completely - I'm not sure evangelism
belongs on this page.

- Add a sentence at the end of the paragraph that starts, "Once you've
read a tutorial" that says, "Many other resources are listed in
BeginnersGuide/Help."

On the BeginnersGuide/NonProgrammers page, I agree, Guido's tutorial
probably shouldn't be listed first even with the disclaimer. It goes way
to fast for a beginner. Alan Gauld's tutorial is very popular on the
tutor list, so is A Byte of Python (which is not listed on the
NonProgrammers page). I would list them first. Or maybe take a vote on
the tutor list for favorite beginner's tutorial.

That should help a little, maybe we won't confuse the newbies before
they even get to an interpreter prompt.

Kent

PS I am aware of the usual SF bug report procedure for docs, does it
apply to these pages? I don't know, they don't have the usual "About
this document" link at the bottom. I'm happy to submit a patch if that
will help. Otherwise I'm not sure what "the Python community as a whole
[taking] this on board" should look like.

 

[skip]

Steven> What I don't know is how it would look after thousands of people
Steven> using it. I know that I probably only have 10 modules or so
Steven> that I consistently need to check the docs for. Your hack above
Steven> would conveniently place those all at the top if I was the only
Steven> user. But are those 10 modules the same 10 modules that other
Steven> folks need? I don't know...

Is suspect most people need help with a fairly common module subset on a
regular basis. This won't provide a cache with a 100% hit rate, but the
cost of a cache miss isn't all that high. Also, you might discover some
useful modules you hadn't used before simply because they are frequently
referenced.

Skip

 

[BartlebyScrivener]

Yep, Guido's tutorial belongs on the Python for Programmers page where
people know who he is and are able to understand him.

Alan Gauld's tutorial is very popular on the
tutor list, so is A Byte of Python (which is not listed on the
NonProgrammers page). I would list them first. Or maybe take a vote on
the tutor list for favorite beginner's tutorial.

And perhaps How To Think Like A Computer Scientist. Then maybe
introduce them with a single sentence like:

"Python is so easy to learn and immediately useful that many popular
tutorials use Python to teach computer programming."

 

[skip]

Kent> OK I'll bite. That Beginners Guide page has bugged me for a long
Kent> time. It's a wiki page but it is marked as immutable so I can't
Kent> change it.

That's because for some reason it is one of the top two or three most
frequently defaced pages on the wiki. We got tired of having to revert
changes to it every day or two. I'll take a look at incorporating your
suggestions.

Skip

 

[BartlebyScrivener]

Might be better as:

"Many popular tutorials use Python to teach computer programming,
because Python is free, easy to learn, immediately useful, and fun!"

 

[Mark Jackson]

That's pretty cool. What I don't know is how it would look after
thousands of people using it. I know that I probably only have 10
modules or so that I consistently need to check the docs for. Your hack
above would conveniently place those all at the top if I was the only
user. But are those 10 modules the same 10 modules that other folks
need? I don't know...

Of course, the only way to find out is to try...

Or you can just look up the module you need to write a 'bot to
constantly look up the docs for your favorite 10 modules. . . .