[docs] Issue: no reference to bytes alias in documentation for 2.6.x and 2.7 (related to closed issue 1865)

[Sam Thompson]

Sandro,

On 2011/08/13 05:22, Sandro Tosi wrote:
> Hello Sam,
> you wrote a lot, I'll try to reply to all your points, but I'll be
> dense: don't take thta for disrespect.
None taken. I appreciate you've a lot to do.
> On Thu, Aug 11, 2011 at 04:00, Sam Thompson<python at samthompson.com>  wrote:
>> Sandro,
[snip]
>> Thanks for explaining this. I could not find any mention of this in the
>> documentation itself. While I expect this may be obvious to those "in the
>> know", can I suggest that this important policy be explicitly stated at the
>> head of the documentation that this applies to, so that:
>> a) people don't waste your time filing bugs for things you have a policy not
>> to fix (note that I'm complaining about the policy - it's fine), and
>> b) people know that the documentation is not necessarily 100% to be relied
>> upon (in light of your comment below about backporting fixes), or
>> alternatively, remove this documentation and redirect visitors to the up-to
>> date version.
> You're actually suggesting to add a banner to every single page of doc
> for older release, which is unfeasible. We provide documentation for
> older versions "as was" when that version was last released, I don't
> see the point in explaining what's the status of a specific version in
> its doc.
There is more than one way to address this. As I stated earlier, I 
respect the project's decision not to maintain old versions of the 
documentation. But I have noticed that when projects still offer old 
versions of code or other material for access or download, they are 
usually pretty clear about the fact that it's unmaintained, at least at 
the entry points/download links. I still haven't seen a reference to the 
policy, on python.org, *outside* of the actual docs themselves.

There probably are SSI or other script based solutions (I don't know, 
maybe Python?) that could be used to tag each of these old pages, even 
if you aren't editing them individually; I disagree that it's unfeasible 
entirely, even though I'm not suggesting this approach.
> python.org/doc makes quite clear what are the supported doc version,
> linking only one for 2.x and 3.x .
This is an interesting point. The very first link in the body of this 
page links to a page that lists all the old versions; 
http://www.python.org/doc/versions/, where I don't even need to make up 
the URL to get old documents. So in addition to the links in the 
documentation navigation itself to previous versions, there's actually a 
direct link to each old version. Note, I'm not saying this is a bad 
thing, but this is a perfect candidate page in your currently maintained 
web site (outside of the documentation itself) where a simple sentence 
added at the head, e.g. "Please note that only the latest documentation 
in the 2.x and 3.x series is actively maintained". That's one change to 
one document. I'd say that's feasible, and expresses the policy succinctly.
> [snip]
>
>> It may be worth providing some more general guidance to users in the
>> documentation introductory section(s) about the best way to find out which
>> versions support which language constructs, if old documentation isn't it.
>> Maybe the "What's new in x?" lists?
> that's exactly the entry point you're looking for: just note that not
> every change ends up there.
Thanks for these suggestions. The fact that not every change is not in 
these documents may limit their utility to answer my question "which 
version introduced feature x?". However, I found references to bytes 
literals in the "what's new in 2.6", so I'm comfortable with this advice 
as an approach to my problem in general.
>> The links you're using to access teh documentation (I don't know if
>> only for showing the problem or as a general use) points to a specific
>> release, that will no longer be updated. So if you want to refer to
>> the lastest 2.x documentation the correct link is:
>>
>> http://docs.python.org/
>>
>> and for Python 3.x it is:
>>
>> http://docs.python.org/py3k/
>>
>> The link I used to access 2.6.7 was in the left navigation of the site at
>> the link http://docs.python.org/ under "Docs for other versions". It's true
> exactly, so you didn't use the latest documentation available :) of
> course, that's related a version of Python you don't have on your
> machine.
OK, but I was trying to answer a question about which versions would 
support the b"" literal feature. I knew it wasn't the latest version. At 
the time, I didn't know it wasn't correct, because it wasn't maintained. 
All that needed to change to fix this issue was to disclose this, 
somewhere where I could have seen it. Even better, provide the advice on 
the page http://www.python.org/doc/versions/ in addition to my previous 
suggestion, viz. "Please note that only the latest documentation in the 
2.x and 3.x series is actively maintained. For information on support in 
previous versions, please refer to the "what's new" documentation".
>> that the URLs accessed for other specific releases before 2.7.2 and 2.6.7
>> were formed by extrapolation, in order to work out what versions of the
>> documentation were affected by the perceived issue. That exercise was
>> ultimately worthless, given the policy as now stated.
>>
>> Instead, my report should have been against the current, maintained 2.x
>> documentation, i.e. "Can you please add a reference in this page saying
>> which version this significant change to string literals was made?". If you
> sometimes it is done, for example in case we add new methods there's
> often a "Added in: X.Y" tag at the end.
I think this change is worthy, particularly as the old docs are 
incorrect. Just my view though.
>> take none the other suggestions on board, which is reasonable given their
>> scope and impact, can I strongly urge you to at least update the current
>> versions of the 2.x and 3.x document for lexical analysis to this effect?
> It *is* fixed, as you said, in 2.7.1 and 2.7.2 : the latter version is
> the current one, so case closed.
That's your prerogative, of course. The correctness of the current 
versions was never the problem in relation to this feature. With 
respect, I still think there's a good argument for changes to:
a) Reflect the current policy on documentation maintenance clearly, on 
http://www.python.org/doc/versions/ at the very least.
b) In the case of the Bytes literal change, to add the "Added in: x.y" 
tag you mentioned to the lexical analysis pages for all currently 
maintained document versions.

If you're still not convinced, that's fine; I'll leave it there.

Regards,
Sam.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20110813/476f9aec/attachment.html>