Reorganizing python.org (was: Why isn't pychecker...)

[Edward K. Ream]

Hi All,

The main page at python.org is getting too long, IMO.  At some
point all the links on the main page become more clutter than helpful. 
I have lots of experience organizing things into outlines ;-)  It would
be best, I think, to create some "second level" pages referenced from
python.org, something like this:

python.org
  a page about releases of python itself
    a download page
  a page about major tools, idle, pychecker, pyunit,
    with links to the commercial products page,
  a page about related products & tools,
    MacPython, Jython, Pippy, Tkinter, etc.
  a links page, containing subpages or subsections for
    commercial products
  an events page
  the commercial products page.
  etc.

The main rules of thumbs in any reorganization:

  Everything significant should be 1 or 2 clicks away from python.org.
  Everything significant should have its own place (maybe off-site).
  Every on-site page should mostly fit on a screen.

In short: place for everything, and everything in its place.

If more was "offloaded" to second-level pages we would get two big
additional benefits:

1. There can be more second level pages so the material can be organized
more effectively.

2. Each page, covering less, can do it better.  It can be more "relaxed"
because more will fit on the page.  This applies to top-level pages as
well as secondary pages.

I find this error all over the web: we try to cram too much onto a
single page, especially reference pages, with the result that one is
constantly scrolling to find what one wants.  This wastes huge amounts
of time and is hard on the eyes.  The solution is always the same,
to reorganize the top-level page so that it can be seen at a glance, and
add at least one extra level of organization.

Examples:  http://python.org/doc/current/ fits on a page,
C:\Python22\Doc\lib\lib.html does not.  C:\Python22\Doc\lib\lib.html
would be so much easier to use if it contained only the top-level
entries, that is, intro, front matter, entries 1-20, entries A,B,C and
index.  All pages can be more informative, and more relaxed.

Another example, the otherwise superb intro to Tkinter,
http://www.pythonware.com/library/tkinter/introduction/index.htm
would be vastly more useful if it fit on a single page.  Once again,
first and second level pages could be both more useful and more relaxed.

The Tk man pages themselves are well organized except for the very
bottom pages, e.g.,
http://tcl.activestate.com/man/tcl8.4/TkCmd/menubutton.htm
which cram everything about a particular class in one humongous mess. 
Perhaps this is done so that is can be printed as reference.  If that is
a goal, one can keep the bottom level page and add a mid-level page
consisting of links into the bottom level page.  The mid-level pages
would contain real information(!), viz., the "big picture" of what is
contained in bottom-level pages.

As I write this, I realize that Leo's own "Complete Table of Contents",
http://personalpages.tds.net/~edream/leo_TOC.html, is too long and could
profitably be reorganized using these rules of thumb. OTOH, Leo's
on-screen reference, LeoDocs.leo, is organized this way (and the
user can reorganize it at will.)
  
Browsing through Section 4 of the FAQ I came across 4.49 re pyunit,
which I had also missed.  Section 4 seems to be a catch-all, and too
long.  Taking these rules of thumb further, it might make sense to split
section 4 into several sections: programming tools, like pychecker,
pyunit and idle, etc., questions about basic constructs, and questions
about typical errors.  It would be easier to find things.

Anyway, this is how I would organize things. YMMV.  If people are
interested, I would be happy to work on a reorganization of python.org. 
And yes, this posting violates these principles, as it hardly fits on
any monitor :-)

Edward
--------------------------------------------------------------------
Edward K. Ream   email:  edream at tds.net
Leo: Literate Editor with Outlines
Leo: http://personalpages.tds.net/~edream/front.html
--------------------------------------------------------------------