<br><div class="gmail_quote">On Fri, Oct 26, 2012 at 11:22 PM, Nick Coghlan <span dir="ltr"><<a href="mailto:ncoghlan@gmail.com" target="_blank">ncoghlan@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div class="im">On Sat, Oct 27, 2012 at 3:44 PM, Yury Selivanov <<a href="mailto:yselivanov.ml@gmail.com">yselivanov.ml@gmail.com</a>> wrote:<br>
> Start with docs switching to py3k by default. That shouldn't be harmful<br>
> (and I hope that my docs theme patch will be accepted soon).<br>
<br>
</div>Actually, there are at least a few very real harms that come from<br>
switching the docs over:<br>
1. Many third party Python 2 tutorials include links to our docs. We<br>
can't magically reach out to those sites and update their links, so<br>
they will end up linking to Python 3 resources from Python 2 ones<br></blockquote><div><br></div><div>And many tutorials are not intentionally version specific.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
2. It breaks links on sites like Stack Overflow and in mailing list<br>
archives and our own bug tracker, which currently link to the main<br>
docs to explain Python 2 behaviour<br></blockquote><div><br></div><div>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.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
3. it completely breaks direct hyperlinks to names that no longer<br>
exist in Python 3 (even the ones that exist under new names)<br></blockquote><div><br></div><div>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)</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">So that's my concrete proposal:</blockquote><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
1. We pick a date (June next year sounds about right)<br>
2. We pick a stable URL prefix for the Python 2 docs (I vote "/2.x/")<br>
3. We start redirecting affected pages immediately<br>
4. We add a notice like the one above to the home page of the 2.7<br>
docs, announce it on the PSF blog, announce it far and wide<br></blockquote><div><br></div><div class="gmail_quote">I think this following proposal provides a better user experience. If you don't think this is better, why?</div>
<div class="gmail_quote"><br></div><div class="gmail_quote">2. Pick a stable url for docs and a way for referrers to select the referenced version when that matters</div><div class="gmail_quote"><br></div><div class="gmail_quote">
Examples:</div><div class="gmail_quote"> (a) <a href="http://docs.python.org/dev/library/os.html#os.walk">http://docs.python.org/dev/library/os.html#os.walk</a> -- displays user's preferred version (see below)</div>
<div class="gmail_quote"><div class="gmail_quote"> (b) <a href="http://docs.python.org/dev/library/os.html?version=2.7#os.walk">http://docs.python.org/dev/library/os.html?version=2.7#os.walk</a> -- displays version 2.7 if user does not have user's preferred version</div>
<div><div class="gmail_quote"> (c) <a href="http://docs.python.org/dev/library/os.html?exactversion=2.7#os.walk">http://docs.python.org/dev/library/os.html?exactversion=2.7#os.walk</a> -- always displays version 2.7 (discouraged unless talking specifically about that version)</div>
</div><div><br></div></div><div class="gmail_quote">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.</div>
<div class="gmail_quote"><br></div><div class="gmail_quote">4. Make the version number more prominent in case (c) so user will be aware that they are not seeing their preferred version.</div><div class="gmail_quote"><br>
</div>
<font face="arial, helvetica, sans-serif">--- Bruce<br></font></div>