Redesign of Python site

[Peter Hansen]

So, are the modified links at http://www.amk.ca/python.org.html
an improvement? Note the different sidebar and top navbar links.

I think that's a distinct improvement, although I'd suggest putting
the Documentation section (in the sidebar) _first_ rather than second
after the Versions section. I'd also move FAQ up to right under "What
is Python?".

Although the FAQ has grown a little too large for its current structure,
I think, more people should spend the time to read the whole thing, and
perhaps would in time for it to be useful (i.e. before they ask a FAQ)
if it were more prominent.

(You mention different top navbar links but they look the same to
me, if you're talking about the Home/Search/Download stuff at the top.)

-Peter

 

[A.M. Kuchling]

I think that's a distinct improvement, although I'd suggest putting
the Documentation section (in the sidebar) _first_ rather than second
after the Versions section.

Really? I envision people wanting information on a specific version first,
only later going to the more generic items under "documentation".
Do other people think this would be a good idea?

I'd also move FAQ up to right under "What
is Python?".
Done.

(You mention different top navbar links but they look the same to
me, if you're talking about the Home/Search/Download stuff at the top.)

Oh, I'm an idiot and dropped an old version of the page on top of it.
Updated now, at same URL as before. The navbar changes are: 1) dropping
SIGs and Help, 2) adding a not-yet-written "Contact us" page and a link to
the site map.

--amk

 

[Peter Hansen]

Really? I envision people wanting information on a specific version first,
only later going to the more generic items under "documentation".

I suppose it depends a lot on which group we're trying to optimize for.
I was thinking of newcomers, especially people we want to send to python.org
so they will stop asking FAQs. The closer the intro stuff is to the top,
provided it's a small set of links, the better, in my view.

I can see the case you make as well.

Ah, now I see that you misinterpreted my first comment, which was not
actually suggesting moving those two links to the very top, but merely
moving the FAQ link to just under the "What is" link, where the latter
used to be.

The best discoveries are often accidents: I like what you've done. I
say keep the "versions" section right where you've got it, with the other
two above like that. Excellent!

Oh, I'm an idiot and dropped an old version of the page on top of it.
Updated now, at same URL as before. The navbar changes are: 1) dropping
SIGs and Help, 2) adding a not-yet-written "Contact us" page and a link to
the site map.

Looks good, too.

Not that this point is necessarily worth considering, but I note that
my brain perceived several of the vertically stacked pairs of links in
that top navbar _together_, leading to a fraction of a second of confusion.
They appeared to read "Download documentation", "Developers community",
and "Search Site map". The old ones are even weirder when read this way:
"Search Developers" and "Download Community"! Perhaps a tiny bit of
visual cruft to separate these would be worth considering, like maybe a
bullet in front of each, or square brackets, or more vertical space.
(Yeah, I'm really picking nits with this one.

-Peter

 

[Skip Montanaro]

amk> I envision people wanting information on a specific version first,
amk> only later going to the more generic items under "documentation".
amk> Do other people think this would be a good idea?

I think docs are more important than specific versions. Sure, the first
time they come to the site they'll be looking for "Python 2.3". But most
times after that they'll want documentation. The most frequent page I visit
on the site is

http://www.python.org/dev/doc/devel/modindex.html

That far outpaces any other page on the site, even the home page, so I
bookmarked so it's one click away.

Skip

 

[Gary Feldman]

Not that this point is necessarily worth considering, but I note that
my brain perceived several of the vertically stacked pairs of links in
that top navbar _together_, leading to a fraction of a second of confusion.

I agree, but it's worse than that.

First, when you get used to useless banners being topmost on the page, you
tend to skip right over them. I know I've made many a trip to the Python
site without noticing that there were links up there. Put the banner
header on top, with the horizontal menu below it. (Yes, this will
temporarily annoy the folks who are used to the current layout, but no
significant change can avoid all temporary annoyances.)

Second, it's just way too busy and redundant. It's more thn simply the
vertical alignment; there are too many items in that section. (Actually,
there are two many static links on the entire page - I counted 45, not
including the announcements).

The horizontal banner really only needs a handful of items:
documentation
downloads
community
search (preferably with a quick search box)
contact us

"Home" is unnecessary; use the logo in the upper left for home on all pages
(yep, consistent navigation on all pages is a plus). "Developers" is
ambiguous. (A newcomer will think it means someone trying to develop with
Python as opposed to maintain Python.) It's also a sufficiently small
number as to not need top billing - as much as they deserve tons of credit.
Both SIGs and Developers should be subsets of Community (i.e. you there via
the Community link, at least as far as the horizontal navigation bar is
concerned). Documentation implies Help, and Help implies Documentation, so
we don't need both in the horizontal bar.

The basic point is that the static appearance of the horizontal navigation
bar must be kept short and simple, with no ambiguous choices. If you want
more choices via popups for the JavaScript browsers that's ok, so long as
the top level items that everyone case see are active links as well (i.e.
it still works with JavaScript disabled).

(Yeah, I'm really picking nits with this one.

No, you're not picking nits, and that's one of the problems with one school
of old-time engineering mentality. Namely, the minimalization of usability
issues. It's ironic that there are foks who might spend a few hours to
squeeze a few milliseconds out of an algorithm, but would dismiss a half
second as a nit, or not important because you can learn to deal with it.
If you stumbled over it, chances are that other people stumbled over it,
and it all adds up. And humans shouldn't have to learn to deal with
unsatisfactory UIs.

Gary

 

[Graham Fawcett]

amk> I envision people wanting information on a specific version first,
amk> only later going to the more generic items under "documentation".
amk> Do other people think this would be a good idea?

I think docs are more important than specific versions. Sure, the first
time they come to the site they'll be looking for "Python 2.3". But most
times after that they'll want documentation. The most frequent page I visit
on the site is

http://www.python.org/dev/doc/devel/modindex.html

That far outpaces any other page on the site, even the home page, so I
bookmarked so it's one click away.

Interesting point. It might prove useful to those redesigning the
site, or discussing its redesign, to examine either

-- python.org's Web logs, if available, or

-- a Google of "python siteython.org"

to determine frequencies of visits to various parts of the site. (I am
assuming, based on minimal knowledge of Google's ranking algorithms,
that the most "relevant" pages will be close to the top of the Google
list.)

Here's a fun exercise for someone with some time on their hands:

Mirror the larger part of the Python site. Then apply extra formatting
to each page, and to links on each page, indicating how "hot" they
are, based on frequencies determined from the logs or Google. For
example, my Google search (above) would suggest that the home page and
the tutorial page are both "hot", so both these pages and any links to
these pages would appear in a warm colour; links to "Python Patch
Submission Guidelines" appears on Google's Page 10 (today, anyway), so
it would get a cool-colour treatment.

At a glance, this should show which parts of the site, and which
links, are "used" and which are "not used" (relatively, by the past
and present audiences of the site, of course).

If you are colour-blind (I mean, chromato-visually impaired), perhaps
you could use various font sizes instead of colours.

I leave the implementation as an exercise for the student. ;-)

Of course, the colour map describes past behaviour, and conclusions
drawn from examining such a "coloured" site might reinforce past usage
patterns, which may or may not be favourable, depending on your point
of view.

Best,

-- Graham

P.S. If someone implemented this, I would get my boss to buy a boxed set.
And I'll trade the rights for a canoe.
;-)

 

[Bengt Richter]

amk> I envision people wanting information on a specific version first,
amk> only later going to the more generic items under "documentation".
amk> Do other people think this would be a good idea?

I think docs are more important than specific versions. Sure, the first
time they come to the site they'll be looking for "Python 2.3". But most
times after that they'll want documentation. The most frequent page I visit
on the site is

http://www.python.org/dev/doc/devel/modindex.html

That far outpaces any other page on the site, even the home page, so I
bookmarked so it's one click away.

For the most part, I use downloaded HTML docs from my HD. And a command line
hack to search with regex the index page for links to the individual module docs
and/or launch the browser to a particular doc. E.g., (the opts handling code is a bit weird,
just a quick experiment, not meant as a model ;-)

[ 7:36] C:\pywk\clp>modoc

Usage: modoc.py [-h] [-re | -ire ] [-href] pattern
Without opts, pattern is taken as a module name to start browser showing docs for.
With opt(s):
-re: pattern is taken as regex to print available matching doc names
-ire: same as -re but case insensitive
-href: prints doc href paths along with names found.
-h: print this

Doc info is retrieved from the html file defined by environment name PY_DOC_INDEX,
e.g., modindex.html and this is located (along with pages therefrom referenced)
by prefixing the string defined by PY_DOC_PREFIX, e.g., D:/Python23/Doc/ (note
forward slashing and ending slash). The ref_name_patt regex may need change if
generated documentation links change format.

[ 7:37] C:\pywk\clp>modoc -ire os
MacOS TERMIOS macostools os
os.path ossaudiodev posix posixfile
termios
[ 7:37] C:\pywk\clp>modoc -re os
macostools os os.path ossaudiodev
posix posixfile termios
[ 7:37] C:\pywk\clp>modoc os.path

(browser pops up with os.path doc).

Oh, I forgot:

[ 7:39] C:\pywk\clp>modoc -re os -href
macostools: 'mac/module-macostools.html'
os: 'lib/module-os.html'
os.path: 'lib/module-os.path.html'
ossaudiodev: 'lib/module-ossaudiodev.html'
posix: 'lib/module-posix.html'
posixfile: 'lib/module-posixfile.html'
termios: 'lib/module-termios.html'

I was thinking of expanding it to cover more of the doc hierarchy, but never got a round tuit.
In case someone want to use/improve it:
(Note the
PY_DOC_PREFIX = os.environ.get('PY_DOC_PREFIX', r'D:/Python23/Doc/')
PY_DOC_INDEX = os.environ.get('PY_DOC_INDEX', r'modindex.html')
lines, which you may want to change for your system setup).

----< modoc.py >---------------------------------------------------------------------------
# modoc.py -- quick way to get to module docs from command line
"""
Usage: modoc.py [-h] [-re | -ire ] [-href] pattern
Without opts, pattern is taken as a module name to start browser showing docs for.
With opt(s):
-re: pattern is taken as regex to print available matching doc names
-ire: same as -re but case insensitive
-href: prints doc href paths along with names found.
-h: print this

Doc info is retrieved from the html file defined by environment name PY_DOC_INDEX,
e.g., modindex.html and this is located (along with pages therefrom referenced)
by prefixing the string defined by PY_DOC_PREFIX, e.g., D:/Python23/Doc/ (note
forward slashing and ending slash). The ref_name_patt regex may need change if
generated documentation links change format.
"""
__version__ = '0.10a'

# Original code by Bengt Richter, offered for free use, with no warranty of any kind.
# v0.1a: 20030813 13:29:40
# + docs and untested env variable defs for doc locs
# + using webbrowser module to start browser instead of os.system

# handy to run from c:\util\modoc.cmd wrapper, e.g.,
# @PYTHON c:\pywk\ut\modoc.py %*
import re, os, webbrowser

PY_DOC_PREFIX = os.environ.get('PY_DOC_PREFIX', r'D:/Python23/Doc/')
PY_DOC_INDEX = os.environ.get('PY_DOC_INDEX', r'modindex.html')

def dispmod(namex='', **opts):
"""Display module doc via browser or search names for match. See module doc."""
page = file(PY_DOC_PREFIX+PY_DOC_INDEX).read()
ref_name_patt = r'<dt><a href="([^"]+)"><tt class="module">([^<]+)' #XXX brittle
rx = re.compile(ref_name_patt)
modict = dict([(name, ref) for ref,name in rx.findall(page)])
names = modict.keys()
names.sort()
if opts:
regex = namex # default case sensitive match
if 're' in opts: pass
elif 'ire' in opts:
regex = '(?i)'+namex
elif 'all' in opts:
regex = None
if regex:
rx = re.compile(regex)
names = list(filter(rx.search, names))
names.sort()
for i, name in enumerate(names):
if 'href' in opts:
print '%19s: %r' % (name, modict[name])
else:
if i and not i%4: print
print '%-19s' % name,
else:
namex = namex.lower()
for name in names:
if name.lower() == namex:
webbrowser.open_new('%s%s' % (PY_DOC_PREFIX, modict[name]))
return
raise SystemExit, 'Module "%s" not found.' % namex

if __name__ == '__main__':
import sys
args = sys.argv[1:]
if not args or '-h' in args: raise SystemExit, __doc__
callargs=[]; callkw={}
while args:
arg = args.pop(0)
if arg.startswith('-'):
callkw[arg[1:]]=True
else:
callargs.append(arg)
dispmod(*callargs, **callkw)

 

[A.M. Kuchling]

The horizontal banner really only needs a handful of items:

Good suggestion; I've updated http://www.amk.ca/python.org.html to match.
The resulting top bar, with only six options, is quite nice.

Should there be a sidebar link to the development version of the docs, as
well as the 2.2/2.3 versions? What to call it, so that newbies don't
stumble into it by accident and wonder why some features are missing from
their 2.3 installation? "In development", "CVS version", "Development
draft", something else?

--amk

 

[Gary Feldman]

Should there be a sidebar link to the development version of the docs, as
well as the 2.2/2.3 versions? What to call it, so that newbies don't

Let me answer this way: There should be at most one direct link to
developer resources in the top and side menu areas combined. Python
developers will certainly be able to find their way around, and will
probably rely on bookmarks directly to the developer area.

Depending on what winds up in the main area, I can imagine an additional
entry there, but not near the top.

Gary