[Python-ideas] docs.python.org

[Bruce Leban]

On Fri, Oct 26, 2012 at 11:22 PM, Nick Coghlan <ncoghlan at gmail.com> wrote:

> 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
>

And many tutorials are not intentionally version specific.


> 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
>

However, just because stack overflow and other sites link to 2.x docs
doesn't mean that the user wants to read the 2.x docs. Scenario: I'm using
3.x, I go to stack overflow to find out how to do something. it links to
the docs for the old version which is inaccurate for me. What I want is to
be able to quickly get to the doc that's relevant to *my* version.


> 3. it completely breaks direct hyperlinks to names that no longer
> exist in Python 3 (even the ones that exist under new names)
>

Urls for things that have been renamed should redirect to the appropriate
pages (whether docs on the new thing or an explanation of why this feature
doesn't exist in that version). This should work both forwards (2.x feature
renamed in 3.x) and backwards (3.x feature doesn't exist in 2.x)


> 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
>

I think this following proposal provides a better user experience. If you
don't think this is better, why?

2. Pick a stable url for docs and a way for referrers to select the
referenced version when that matters

Examples:
    (a) http://docs.python.org/dev/library/os.html#os.walk -- displays
user's preferred version (see below)
    (b) http://docs.python.org/dev/library/os.html?version=2.7#os.walk --
displays version 2.7 if user does not have user's preferred version
    (c) http://docs.python.org/dev/library/os.html?exactversion=2.7#os.walk--
always displays version 2.7 (discouraged unless talking specifically
about that version)

3. All the pages have a version picker (as previously discussed). The
dropdown to pick a version number could also have a way to pick the user's
preferred version and save it in a cookie.

4. Make the version number more prominent in case (c) so user will be aware
that they are not seeing their preferred version.

--- Bruce
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-ideas/attachments/20121027/d2900b9d/attachment.html>