[Python-Dev] Misc/maintainers.rst

[Fred Drake]

On Thu, Sep 17, 2009 at 10:38, Georg Brandl <g.brandl at gmx.net> wrote:
> So the plan would be to consolidate these into another set of rst  
> docs,
> having them in the repo, editable by every committer, as well as  
> published
> somewhere on python.org (devdocs.python.org or somesuch).

On Sep 17, 2009, at 1:56 PM, Brett Cannon wrote:
> dev.python.org would be nice to have, from which we can simply
> redirect www.python.org/dev/ to dev.python.org. www.python.org/dev/
> can then get cleaned up be made simpler to navigate and more obvious
> for how people can get started.

Many years ago, we decided to add docs.python.org with the "current"  
version of the documentation, so people would be able to find the docs  
more easily.  Since then, we've had problems with keeping  
docs.python.org and www.python.org/doc/ in sync, and with different  
styles being applied to the sites.

One of the reasons www.python.org/doc/ was considered less  
discoverable was the about of only-sometimes-interesting information  
there; docs.python.org contains only "current" docs (for some vague  
notion of current and only, given that dev builds and both Python 2  
and Python 3 versions).  Some claimed that having "docs" at the front  
of the URL helped, though I don't recall why.

I don't know whether users consider the docs more discoverable than  
they used to; if anyone can provide information about that (now sure  
what indicator would make even sense), that might be informative.

The overload problem is one we *don't* have for developer  
documentation; the difficulty is in discovering what exists at all.

+1 on moving the developer docs to subversion

+0 on exposing them online

-0 on adding another domain name


   -Fred

-- 
Fred Drake   <fdrake at pobox.com>