Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Python > Re: Documentation suggestions

Reply
Thread Tools

Re: Documentation suggestions

 
 
Michael Spencer
Guest
Posts: n/a
 
      12-06-2005
A.M. Kuchling wrote:
> Here are some thoughts on reorganizing Python's documentation, with
> one big suggestion.
>


Thanks for raising this topic, and for your on-going efforts in this field.

I use the compiled html help file provided by PythonWin, which includes all the
core documentation. I usually use the index interface, not the table of
contents (the main exception is the LibRef, see below). In this form, the
structure of the documentation is less important than how good the index is.
Unfortunately, the "additional documentation', including, in particular, your re
HowTo is linked, but not indexed and is therefore less accessible.

> The tutorial seems to be in pretty good shape because Raymond

....
Agreed, but as you say below, there may be friendlier forms available for the
first-timer.

....
> There's another struggle within the LibRef: is it a reference or a
> tutorial?


I want it to help answer questions of the form "What's in the the library that
might help me do x?" For this case, some of the current section structure is
not that helpful. "Miscellaneous Services", in particular, gives no clue to
treasures it contains. I would prefer, for example, to see the data structure
modules: collections, heapq, array etc... given their own section.
Documentation/testing, cmd/options might be other candidates to draw together
currently related material more meaningfully.

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;


A reference, yes, but not necessarily alphabetical if another organization is
more communicative. itertools is a good example where alphabetic presentation
makes perfect sense, since the functions are more-or-less peers; the math
functions are usefully classified by topic; textwrap presents most commonly-used
functions first; several modules document classes before convenience functions.
Each of these has its merits, and I don't see a lot of mileage in trying to
standardize them, given how varied modules are. However, whatever the reference
structure, examples add significantly to the value to me.

....

> I suspect the Achilles' heel of the docs is the Language Reference.
> Put aside the fact that it's not up to date with new-style classes and
> other stuff; that would be fixable with some effort.
>


> To some degree, the guide is trying to be very formal; it's written
> like a specification for an implementor, not a document that people
> would read through. But there's no other way for people to learn
> about all the special object methods like __add__; the tutorial can't
> cover them all, and the LibRef doesn't describe them. So the newbie
> is stuck.


I find very little of value to me in the Language Ref. Special methods are the
crucial exception. Perhaps they, together with a description of class semantics
(including metaclasses and descriptors) could be moved to the Built-in types
section of the LibRef, where some related material is already.

I don't know whether the rest of the Language reference is of use to
implementers, but given the proliferation of implementations beyond Cpython
(Jython, IronPython, pypy) I would speculate that a formal specification is now
more important rather than less. However, perhaps it would be possible to
express the specification more succinctly via tests instead of a manual.

....
>
> Perhaps we need a friendlier counterpart to the RefGuide, something
> like the 20-page introduction to Python at the beginning of Beazley's
> Essential Reference:


I did't know this source, but I just skimmed it at
http://www.amazon.com/gp/reader/0735...51#reader-page
(not sure if this is a session link), and I agree it's a very clear
introduction. Probably better first reading than the existing tutorial.

....


Michael

 
Reply With Quote
 
 
 
 
Colin J. Williams
Guest
Posts: n/a
 
      12-06-2005
Michael Spencer wrote:
> A.M. Kuchling wrote:
>
>> Here are some thoughts on reorganizing Python's documentation, with
>> one big suggestion.
>>

>
> Thanks for raising this topic, and for your on-going efforts in this field.
>
> I use the compiled html help file provided by PythonWin, which includes
> all the core documentation. I usually use the index interface, not the
> table of contents (the main exception is the LibRef, see below). In
> this form, the structure of the documentation is less important than how
> good the index is. Unfortunately, the "additional documentation',
> including, in particular, your re HowTo is linked, but not indexed and
> is therefore less accessible.
>
>> The tutorial seems to be in pretty good shape because Raymond

>
> ....
> Agreed, but as you say below, there may be friendlier forms available
> for the first-timer.
>
> ....
>
>> There's another struggle within the LibRef: is it a reference or a
>> tutorial?

>
>
> I want it to help answer questions of the form "What's in the the
> library that might help me do x?" For this case, some of the current
> section structure is not that helpful. "Miscellaneous Services", in
> particular, gives no clue to treasures it contains. I would prefer, for
> example, to see the data structure modules: collections, heapq, array
> etc... given their own section. Documentation/testing, cmd/options might
> be other candidates to draw together currently related material more
> meaningfully.
>
> 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;

>
>
> A reference, yes, but not necessarily alphabetical if another
> organization is more communicative. itertools is a good example where
> alphabetic presentation makes perfect sense, since the functions are
> more-or-less peers; the math functions are usefully classified by topic;
> textwrap presents most commonly-used functions first; several modules
> document classes before convenience functions. Each of these has its
> merits, and I don't see a lot of mileage in trying to standardize them,
> given how varied modules are. However, whatever the reference
> structure, examples add significantly to the value to me.
>
> ....
>
>> I suspect the Achilles' heel of the docs is the Language Reference.
>> Put aside the fact that it's not up to date with new-style classes and
>> other stuff; that would be fixable with some effort.
>>

>
>> To some degree, the guide is trying to be very formal; it's written
>> like a specification for an implementor, not a document that people
>> would read through. But there's no other way for people to learn
>> about all the special object methods like __add__; the tutorial can't
>> cover them all, and the LibRef doesn't describe them. So the newbie
>> is stuck.

>
>
> I find very little of value to me in the Language Ref. Special methods
> are the crucial exception. Perhaps they, together with a description of
> class semantics (including metaclasses and descriptors) could be moved
> to the Built-in types section of the LibRef, where some related material
> is already.
>
> I don't know whether the rest of the Language reference is of use to
> implementers, but given the proliferation of implementations beyond
> Cpython (Jython, IronPython, pypy) I would speculate that a formal
> specification is now more important rather than less. However, perhaps
> it would be possible to express the specification more succinctly via
> tests instead of a manual.
>
> ....
>
>>
>> Perhaps we need a friendlier counterpart to the RefGuide, something
>> like the 20-page introduction to Python at the beginning of Beazley's
>> Essential Reference:

>
>
> I did't know this source, but I just skimmed it at
> http://www.amazon.com/gp/reader/0735...51#reader-page
>
> (not sure if this is a session link), and I agree it's a very clear
> introduction. Probably better first reading than the existing tutorial.
>
> ....
>
>
> Michael
>

I like the approach but more would be helpful for a current Python,
especially with respect to types/classes. The book is based on Python 2.1.

Colin W.
 
Reply With Quote
 
 
 
 
A.M. Kuchling
Guest
Posts: n/a
 
      12-07-2005
On Tue, 06 Dec 2005 10:29:33 -0800,
Michael Spencer <(E-Mail Removed)> wrote:
> not that helpful. "Miscellaneous Services", in particular, gives no clue to
> treasures it contains. I would prefer, for example, to see the data
> structure modules: collections, heapq, array etc... given their own section.
> Documentation/testing, cmd/options might be other candidates to draw together
> currently related material more meaningfully.


You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
are 'Generic OS Services' and 'Optional OS Services'. These chapters
should be rearranged into more, smaller chapters.

A patch for a draft reorganization is at http://www.python.org/sf/1375417

--amk
 
Reply With Quote
 
Michael Spencer
Guest
Posts: n/a
 
      12-07-2005
A.M. Kuchling wrote:
> On Tue, 06 Dec 2005 10:29:33 -0800,
> Michael Spencer <(E-Mail Removed)> wrote:
>> not that helpful. "Miscellaneous Services", in particular, gives no clue to
>> treasures it contains. I would prefer, for example, to see the data
>> structure modules: collections, heapq, array etc... given their own section.
>> Documentation/testing, cmd/options might be other candidates to draw together
>> currently related material more meaningfully.

>
> You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
> are 'Generic OS Services' and 'Optional OS Services'. These chapters
> should be rearranged into more, smaller chapters.
>
> A patch for a draft reorganization is at http://www.python.org/sf/1375417
>
> --amk

Thanks! That looks like a good start.

I experimented with some more re-organization, but I don't see away to attach
the resulting file in the SF comments, so I'll post it here instead.

Michael



% experimental re-organization of lib.tex,
% from http://www.python.org/sf/1375417

\tableofcontents

% Chapter title:

\input{libintro} % Introduction


% =============
% BUILT-INs
% =============

\input{libobjs} % Built-in Types, Exceptions and Functions
\input{libfuncs}
\input{libstdtypes}
\input{libexcs}
\input{libconsts}



% =============
% BASIC/GENERAL-PURPOSE OBJECTS
% =============

% General object services
\input{libtypes}
\input{libnew}
\input{libweakref}
\input{libcopy}
\input{libpprint}
\input{librepr}

% Strings
\input{libstrings} % String Services
\input{libstring}
\input{libre}
\input{libreconvert}
\input{libstruct} % also/better in File Formats?
\input{libdifflib}
\input{libfpformat}
\input{libstringio}
\input{libtextwrap}
\input{libcodecs}
\input{libunicodedata}
\input{libstringprep}

% Data types and structures
%\input{libdata} % Data types and structures
\input{libdatetime}
\input{libcalendar}
\input{libcollections}
\input{libheapq}
\input{libarray}
\input{libsets}
\input{libsched}
\input{libmutex}
\input{libqueue}
\input{libuserdict} % From runtime. What happened to UserList and UserString?

% Numeric/Mathematical modules
\input{libdecimal}
\input{libmath}
\input{libcmath}
\input{librandom}
\input{libbisect} % is this needed here - more useful in Data types, like heapq?

% Functions, Functional, Generators and Iterators
\input{libitertools}
\input{libfunctional}
\input{liboperator} % from runtime - better with itertools and functional


%\input{libmisc} % Miscellaneous Services


% =============
% DATA FORMATS
% =============

% % File formats
\input{libcfgparser}
\input{libnetrc}
\input{librobotparser}
\input{libcsv}
\input{libstruct} % and in string?

% Big move - include all the markup and internet formats here

% MIME & email stuff
\input{email}
\input{libmailcap}
\input{libmailbox}
\input{libmhlib}
\input{libmimetools}
\input{libmimetypes}
\input{libmimewriter}
\input{libmimify}
\input{libmultifile}
\input{librfc822}

% encoding stuff
\input{libbase64}
\input{libbinascii}
\input{libbinhex}
\input{libquopri}
\input{libuu}
\input{libxdrlib}

\input{markup} % Structured Markup Processing Tools
\input{libhtmlparser}
\input{libsgmllib}
\input{libhtmllib}
\input{libpyexpat}
\input{xmldom}
\input{xmldomminidom}
\input{xmldompulldom}
\input{xmlsax}
\input{xmlsaxhandler}
\input{xmlsaxutils}
\input{xmlsaxreader}
% \input{libxmllib}

\input{libcrypto} % Cryptographic Services
\input{libhmac}
\input{libhashlib}
\input{libmd5}
\input{libsha}

% =============
% FILE & DATABASE STORAGE
% =============

\input{liballos} % File-system services (XXX change header)
\input{libos}
\input{libposixpath} % os.path
\input{libfileinput}
\input{libstat}
\input{libstatvfs}
\input{libfilecmp}
\input{libtempfile}
\input{libglob}
\input{libfnmatch}
\input{liblinecache}
\input{libshutil}
\input{libdircache}

% % Data compression and archiving
\input{libzlib}
\input{libgzip}
\input{libbz2}
\input{libzipfile}
\input{libtarfile}

%\input{libpersistence} % Persistent storage
\input{libpickle}
\input{libcopyreg} % really copy_reg % from runtime...
\input{libshelve}
\input{libmarshal}
\input{libanydbm}
\input{libwhichdb}
\input{libdbm}
\input{libgdbm}
\input{libdbhash}
\input{libbsddb}
\input{libdumbdbm}


% =============
% OS
% =============


\input{liballos} % Generic Operating System Services
\input{libtime}
\input{libgetpass}
\input{libcurses}
\input{libascii} % curses.ascii
\input{libcursespanel}
\input{libplatform}
\input{liberrno}

% % Interprocess communication/networking
\input{libsubprocess}
\input{libsocket}
\input{libsignal}
\input{libpopen2}
\input{libasyncore}
\input{libasynchat}

\input{libsomeos} % Optional Operating System Services
\input{libselect}
\input{libthread}
\input{libthreading}
\input{libdummythread}
\input{libdummythreading}
\input{libmmap}
\input{libreadline}
\input{librlcompleter}

\input{libunix} % UNIX Specific Services
\input{libposix}
\input{libpwd}
\input{libspwd}
\input{libgrp}
\input{libcrypt}
\input{libdl}
\input{libtermios}
\input{libtty}
\input{libpty}
\input{libfcntl}
\input{libpipes}
\input{libposixfile}
\input{libresource}
\input{libnis}
\input{libsyslog}
\input{libcommands}


% =============
% NETWORK & COMMUNICATIONS
% =============

\input{internet} % Internet Protocols
\input{libwebbrowser}
\input{libcgi}
\input{libcgitb}
\input{liburllib}
\input{liburllib2}
\input{libhttplib}
\input{libftplib}
\input{libgopherlib}
\input{libpoplib}
\input{libimaplib}
\input{libnntplib}
\input{libsmtplib}
\input{libsmtpd}
\input{libtelnetlib}
\input{liburlparse}
\input{libsocksvr}
\input{libbasehttp}
\input{libsimplehttp}
\input{libcgihttp}
\input{libcookielib}
\input{libcookie}
\input{libxmlrpclib}
\input{libsimplexmlrpc}
\input{libdocxmlrpc}

\input{netdata} % Internet Data Handling
\input{libformatter}

% =============
% MULTIMEDIA
% =============

\input{libmm} % Multimedia Services
\input{libaudioop}
\input{libimageop}
\input{libaifc}
\input{libsunau}
\input{libwave}
\input{libchunk}
\input{libcolorsys}
\input{librgbimg}
\input{libimghdr}
\input{libsndhdr}
\input{libossaudiodev}



% =============
% PROGRAM FRAMEWORKS/OPTIONS/GUI
% =============
\input{libgetopt}
\input{liboptparse}
\input{libcmd}
\input{libshlex}
\input{liblogging}
\input{tkinter}
% % Internationalization
\input{libgettext}


% =============
% DEVELOPMENT TOOLS
% =============
% % Software development support
\input{libpydoc}
\input{libdoctest}
\input{libunittest}
\input{libtest}

\input{libpdb} % The Python Debugger

\input{libprofile} % The Python Profiler
\input{libhotshot} % New profiler
\input{libtimeit}


% =============
% PYTHON ENGINE
% =============
\input{libpython} % Python Runtime Services

% Runtime services
\input{libsys}
\input{libbltin} % really __builtin__
\input{libmain} % really __main__
\input{libtraceback}
\input{libinspect}
\input{libgc}

% Custom interpreter
\input{libcode}
\input{libcodeop}
\input{librestricted} % Restricted Execution
\input{librexec}
\input{libbastion}

% Runtime environment
\input{libfpectl}
\input{libatexit}
\input{libsite}
\input{libuser}
\input{libfuture} % really __future__
\input{libwarnings}
\input{liblocale} % also in Internationalization

% modules
\input{libimp}
\input{libzipimport}
\input{libpkgutil}
\input{libmodulefinder}


% =============
% PYTHON LANGUAGE & COMPILER
% =============

\input{language} % Python Language Services
\input{libparser}
\input{libsymbol}
\input{libtoken}
\input{libkeyword}
\input{libtokenize}
\input{libtabnanny}
\input{libpyclbr}
\input{libpycompile} % really py_compile
\input{libcompileall}
\input{libdis}
\input{libpickletools}
\input{distutils}

\input{compiler} % compiler package


% =============
% OTHER PLATFORM-SPECIFIC STUFF
% =============

%\input{libamoeba} % AMOEBA ONLY

%\input{libstdwin} % STDWIN ONLY

\input{libsgi} % SGI IRIX ONLY
\input{libal}
\input{libcd}
\input{libfl}
\input{libfm}
\input{libgl}
\input{libimgfile}
\input{libjpeg}
%\input{libpanel}

\input{libsun} % SUNOS ONLY
\input{libsunaudio}

\input{windows} % MS Windows ONLY
\input{libmsvcrt}
\input{libwinreg}
\input{libwinsound}

\appendix
\input{libundoc}

%\chapter{Obsolete Modules}
%\input{libcmpcache}
%\input{libcmp}
%\input{libni}
%\input{libregex}
%\input{libregsub}

\chapter{Reporting Bugs}
\input{reportingbugs}

\chapter{History and License}
\input{license}




 
Reply With Quote
 
rurpy@yahoo.com
Guest
Posts: n/a
 
      12-07-2005

"Michael Spencer" <(E-Mail Removed)> wrote:
> A.M. Kuchling wrote:
> > On Tue, 06 Dec 2005 10:29:33 -0800,
> > Michael Spencer <(E-Mail Removed)> wrote:
> >> not that helpful. "Miscellaneous Services", in particular, gives no clue to
> >> treasures it contains. I would prefer, for example, to see the data
> >> structure modules: collections, heapq, array etc... given their own section.
> >> Documentation/testing, cmd/options might be other candidates to draw together
> >> currently related material more meaningfully.

> >
> > You're right; "Miscellaneous Services" is a grab-bag of stuff, and so
> > are 'Generic OS Services' and 'Optional OS Services'. These chapters
> > should be rearranged into more, smaller chapters.
> >
> > A patch for a draft reorganization is at http://www.python.org/sf/1375417
> >
> > --amk

> Thanks! That looks like a good start.
>
> I experimented with some more re-organization, but I don't see away to attach
> the resulting file in the SF comments, so I'll post it here instead.
>
> Michael

--snip--
> % =============
> % BUILT-INs
> % =============
>
> \input{libobjs} % Built-in Types, Exceptions and Functions
> \input{libfuncs}
> \input{libstdtypes}
> \input{libexcs}
> \input{libconsts}

--snip--

Is this intended as a standalone short term bandaid, or as
part of a more serious attempt to fix the doc problems?

The builtins section should be moved to the language
reference manual. The material it documents is part
of the language definition, not part of an add-on library.

Worse, if it stays in the library reference manual, it will
make it very difficult to fix the language reference manual,
since core parts of the discussion of the language need
to reference these builtins. Rather like a book on the
history of World War 2 saying "For information on the
D-day invasion, please refer to ...". Workable perhaps
but not likely to impress anyone with the competance
of its authors.

There is long history of established prior art when it
comes to documenting computer languages. Is it
really necessary for Python to blaze new ground here?

 
Reply With Quote
 
Fredrik Lundh
Guest
Posts: n/a
 
      12-07-2005
http://www.velocityreviews.com/forums/(E-Mail Removed) wrote:

> The builtins section should be moved to the language
> reference manual. The material it documents is part
> of the language definition, not part of an add-on library.


the standard library is not an add-on. you're confused.

</F>



 
Reply With Quote
 
rurpy@yahoo.com
Guest
Posts: n/a
 
      12-07-2005

Fredrik Lundh wrote:
> (E-Mail Removed) wrote:
>
> > The builtins section should be moved to the language
> > reference manual. The material it documents is part
> > of the language definition, not part of an add-on library.

>
> the standard library is not an add-on. you're confused.
>
> </F>


Your probably talking about internal implementation.
I'm talking about user's perception. A "python" that
had a different set of builtins would not be python.
That makes it more useful to view it as part of the
language, not a library even if it happens to be
implemented that way.

 
Reply With Quote
 
Fredrik Lundh
Guest
Posts: n/a
 
      12-07-2005
(E-Mail Removed) wrote:

> Fredrik Lundh wrote:
> > (E-Mail Removed) wrote:
> >
> > > The builtins section should be moved to the language
> > > reference manual. The material it documents is part
> > > of the language definition, not part of an add-on library.

> >
> > the standard library is not an add-on. you're confused.

>
> Your probably talking about internal implementation.
> I'm talking about user's perception. A "python" that
> had a different set of builtins would not be python.
> That makes it more useful to view it as part of the
> language, not a library even if it happens to be
> implemented that way.


no, I'm talking about how things are used, not how things
happen to look inside your head.

you seem to think that everything that lives in the __builtin__
module are fundamental parts of the language, but that any-
thing that can be explicitly imported into a user module is an
"add-on".

that's not how things work. if you want to move "fundamental
parts" to a different document, you have to move a lot more
than just the functions in the __builtin__ module.

</F>



 
Reply With Quote
 
Ian Bicking
Guest
Posts: n/a
 
      12-07-2005
Fredrik Lundh wrote:
> (E-Mail Removed) wrote:
>
> > The builtins section should be moved to the language
> > reference manual. The material it documents is part
> > of the language definition, not part of an add-on library.

>
> the standard library is not an add-on. you're confused.


I think the point is that there is the core language, and from a user's
perspective builtins and statements and syntax are all the same thing.
When you import a module, it's more-or-less obvious where you find
information about the module (the module index, of course). But
"print", "sorted", and "list" are all equally "built in" in the mind of
a new user. And frankly, though with experience I understand the
categorization, I don't find it particularly compelling.

A new and improved language reference document should deal with all of
these together, I think.

Ian

 
Reply With Quote
 
Fredrik Lundh
Guest
Posts: n/a
 
      12-07-2005
Ian Bicking wrote:

> > the standard library is not an add-on. you're confused.

>
> I think the point is that there is the core language, and from a user's
> perspective builtins and statements and syntax are all the same thing.
> When you import a module, it's more-or-less obvious where you find
> information about the module (the module index, of course). But
> "print", "sorted", and "list" are all equally "built in" in the mind of
> a new user.


so are many standard modules (don't tell me that any real user will
learn all the builtins before she writes her first import statement...)

> A new and improved language reference document should deal with all of
> these together, I think.


wasn't the idea to get rid of the language reference altogether, and
replace it with a better introduction ?

</F>



 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
converting XSD documentation to HTML documentation kev.sully@gmail.com XML 1 09-16-2006 12:09 PM
Documentation suggestions A.M. Kuchling Python 62 12-13-2005 04:26 PM
Re: Documentation suggestions skip@pobox.com Python 3 12-07-2005 03:29 AM
Python documentation: How about structured documentation? Looking for comments/suggestions Kenneth McDonald Python 2 05-06-2004 04:11 AM
Principles of documentation (was: Python Documentation Blows!) Cameron Laird Python 1 04-03-2004 06:54 PM



Advertisments