[Python-ideas] docs.python.org

[Nick Coghlan]

On Sat, Oct 27, 2012 at 3:44 PM, Yury Selivanov <yselivanov.ml at gmail.com> wrote:
> Start with docs switching to py3k by default.  That shouldn't be harmful
> (and I hope that my docs theme patch will be accepted soon).

Actually, there are at least a few very real harms that come from
switching the docs over:
1. Many third party Python 2 tutorials include links to our docs. We
can't magically reach out to those sites and update their links, so
they will end up linking to Python 3 resources from Python 2 ones
2. It breaks links on sites like Stack Overflow and in mailing list
archives and our own bug tracker, which currently link to the main
docs to explain Python 2 behaviour
3. it completely breaks direct hyperlinks to names that no longer
exist in Python 3 (even the ones that exist under new names).

I'm actually wondering if docs.python.org should be updated *now* with
a rewrite rule that redirects to a more explicit docs.python.org/2.x/
URL. At the moment, there is no easy way to get hold of a stable URL
for the Python 2 docs, and nothing we can put in any advance
announcement of a migration to say something like:

"docs.python.org will switch to displaying the Python 3 documentation
by default in June 2013. Please update any direct links that are
intended to refer specifically to the Python 2 documentation by
including a leading '/2.x/' in the path component of the URL. For
example, 'http://docs.python.org/library/os' would become
'http://docs.python.org/2.x/library/os'. Between now and the migration
in June 2013, affected links will be automatically redirected to the
new stable Python 2.x URLs".

So that's my concrete proposal:
1. We pick a date (June next year sounds about right)
2. We pick a stable URL prefix for the Python 2 docs (I vote "/2.x/")
3. We start redirecting affected pages immediately
4. We add a notice like the one above to the home page of the 2.7
docs, announce it on the PSF blog, announce it far and wide

Cheers,
Nick.

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia