Documentation suggestions

[rurpy at yahoo.com]

skip at pobox.com wrote:
> Ian> I think it would be very useful if there was reference (not just
>     Ian> tutorial) documentation for all the syntax, special semantics like
>     Ian> magic methods, and all the functions and objects in builtins.
>
> It's pretty common to have a User's Guide as well as a Reference Manual for
> many applications.  Python has always lacked a User's Guide.
>
> I find it hard to imagine any one person having the time to simply sit down
> and bat out such a tome though.  I'm partial to using wikis as collaborative
> environments.  (They more readily admit a group of people to the process
> without a formal registration process as would doing the whole thing via
> Python's svn repository.)  Creating a UsersGuide section of the Python wiki
> with reST as the markup might be a good place to work on such a beast with
> the goal that it would be a stepping stone to a more standalone document.
>
> Skip

Most of the issues regarding issues like where to "print" and
"sys.write", etc results from a wrong assumtion: that the
Lang ref as only for "language lawyers".  My sense is the
many people see the Lang ref as a Syntax manual.  It doesn't
have to be only that.

My suggestions:
- Keep the basic organization of the Lang Ref the same
but make the entries more accessible to people new to
Python.  If is a reference, keep the BNF, details, etc.
Add (brief, terse!) explanatory material where confusion
may occur.  Add examples!!  (not 1 in 10000 writers can
write clearly enough to do without examples)

- Move Section 2 (builtin types) from the Lib Ref to the
Lang Ref.  This section documents data types, builtin
objects, methods, etc.  These are all language things,
not library things.

- Distinction between Lib and Lang is easy: if you import
it, it goes in Lib.  otherwise it's in Lang.  (If it ain't got ints,
string, None, etc, it ain't the python language.  It could be
python without pprint.)

- Make an exception for sys (document in both, or maybe
full doc in Lib, enough doc in Lang to support the needed
references in Lang, or maybe all in Lang as an exception?)

If the Lang ref is made a ref for the language, the
Lib ref for the library, make them both accessible, then
they both get used as they should.

To me, the difference between tutorial and reference is:
Organization:
  + Ref: organised depth-first.  Each topic is treated fully
  (in complete depth) before the next.
  + Tut: organised breadth-first: broad sweeps are made
  accross the subject matter, then again a greater death,
  then again, etc.
Audience:
  + Ref: material in a section can assume knowlage level
    determined by the material.  (description of metaclass
   stuff can assume user knows basics of class stuff.)
  + Tut: Knowlage level assumed depends on material's
     position in the doc (assumes knowlage of previously
    presented material.)
Purpose:
  + Tut: Teach the language to a user.
  + Ref: Allow the user to find out information about the language
Style:
 + Tut: Often chatty: "Now that we've seen how iterators
      work, lets put that to work"
 + Ref: Terse: "examples:" (but not TOO terse.  Idea is to
    transfer info to reader as effectively a possible.  If it takes
    reader (of the assumed level) 5 minutes of thinking to
    say "oh, now I see" something's wrong.)

Both tutorial material and reference material are desirable but
if resources allow only one reference is better.

A user guide would be great but just an update of the tutorial
and some reorganiztion and expansion of the two primary
references would improve things a lot in the interim.

(sorry for the rough shape this posting is but I've got to run.)