Documentation suggestions

[Rocco Moretti]

A.M. Kuchling wrote:

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