classification
Title: Shelve documentation security warning is not visible
Type: Stage: resolved
Components: Documentation Versions: Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, georg.brandl, python-dev, techtonik
Priority: normal Keywords:

Created on 2013-09-21 12:44 by techtonik, last changed 2013-09-22 12:08 by techtonik. This issue is now closed.

Messages (11)
msg198194 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-21 12:44
This is a follow up to issue #8855. Currently the security warning is completely invisible from Python 2 docs http://docs.python.org/2/library/shelve.html and is located under screen border on Python 3 docs.

The proposal is to move warning out of the description of open() function to paragraph following module description, the same way is it is done for pickle http://docs.python.org/3.3/library/pickle.html
msg198195 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-21 12:44
tag:easy
msg198250 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-09-22 08:45
Using the "warning" directive can be backported from the 3.x docs.

For 3.x, it's already prominent enough. Your "screen border" is not everyone's screen border.
msg198251 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-22 09:21
The scope of warning is wrong. It is not a warning for open() call, and that's why it is easy to miss.
msg198252 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-09-22 09:42
Oh, please. It's big and red and directly below the open() description, how could you miss it?
msg198253 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2013-09-22 09:42
New changeset 1d850260a356 by Georg Brandl in branch '2.7':
Closes #19061: make shelve security warning consistent between 2.x and 3.x.
http://hg.python.org/cpython/rev/1d850260a356
msg198258 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-22 11:08
On Sun, Sep 22, 2013 at 12:42 PM, Georg Brandl <report@bugs.python.org>wrote:

> Oh, please. It's big and red and directly below the open() description,
> how could you miss it?
>

I believe that it is pretty easy with mobile browser due to screen
constraints. Can you test this on your mobile devices?

As for your argument about my border not being everyone's border, I believe
that my border accounts for 18%+ of browser market share.
http://gs.statcounter.com/#mobile_vs_desktop-ww-monthly-201308-201308-bar I
would be even more interested to see docs.python.org stats, which may be
more, because reading docs from tablet is more convenient, or less, because
there tables are not good development platforms for Python.
msg198259 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-09-22 11:11
> I believe that it is pretty easy with mobile browser due to screen
> constraints. Can you test this on your mobile devices?

Sorry, but we don't adapt the docs *content* to any specific device.  You should never only read just a screenful in any case.  This is technical documentation, not a news article!

If you believe that you can improve the docs *design* (the CSS, mainly) to work better on mobile devices, be my guest!  There are certainly optimization opportunities, but that never relieves you of making sure you read the whole content that's relevant to you.
msg198266 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-22 11:42
On Sun, Sep 22, 2013 at 2:11 PM, Georg Brandl <report@bugs.python.org>wrote:

>
> Georg Brandl added the comment:
>
> > I believe that it is pretty easy with mobile browser due to screen
> > constraints. Can you test this on your mobile devices?
>
> Sorry, but we don't adapt the docs *content* to any specific device.  You
> should never only read just a screenful in any case.  This is technical
> documentation, not a news article!
>

I am sorry, but you're misplacing arguments. It looks like this:

me[1]> open() function description is a wrong place for warning that is
related to a whole module
you[2]> common, it is visible, that's the point anyway
me[3]> it is not visible on mobile
you[4]> we do not support mobile

[3] makes your point [2] invalid. And your point [4] doesn't apply as an
answer to [1].

 Now my arguments are:
1. Warning is located in the wrong place (bug is trivial, not important)
2. Wrong place causes problems with mobiles (trivial, somewhat matters)

And you argument that users (or is it for me personally?) should never read
only screenful for a module description is rather strange for the most of
us.

   "Why are things always in the last place you look for them?
    Because you stop looking when you find them."

I highly recommend you to read this book -
http://www.sensible.com/chapter.html - it's awesome.
And just for amusement -
http://uxmyths.com/post/647473628/myth-people-read-on-the-web

> If you believe that you can improve the docs *design* (the CSS, mainly) to
> work better on mobile devices, be my guest!  There are certainly
> optimization opportunities, but that never relieves you of making sure you
> read the whole content that's relevant to you.
>

There is nothing wrong with CSS or mobile design. There is an issue with
the placement of this specific piece of information, which comes detached
from the place (module description) where it belongs. Although the effect
of this bug is partially with background workaround, the cause is still
there.

To make it more real scenario for you. In corporate environment somebody
who issues a recommendation, is not necessarily the person who implements
it. If you're implementing everything yourself, of course you won't miss
the details.
msg198268 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-09-22 11:57
> me[1]> open() function description is a wrong place for warning that is
related to a whole module
> you[2]> common, it is visible, that's the point anyway
> me[3]> it is not visible on mobile
> you[4]> we do not support mobile

Your complaint was that it is "located under screen border".  My reply is that what the "screen border" is is highly device specific and that  we don't cater to specific devices, therefore rejecting your complaint.  I never said "we don't support mobile".  That's it for me and this issue.
msg198270 - (view) Author: anatoly techtonik (techtonik) Date: 2013-09-22 12:08
On Sun, Sep 22, 2013 at 2:57 PM, Georg Brandl <report@bugs.python.org>wrote:

>
> Georg Brandl added the comment:
>
> > me[1]> open() function description is a wrong place for warning that is
> related to a whole module
> > you[2]> common, it is visible, that's the point anyway
> > me[3]> it is not visible on mobile
> > you[4]> we do not support mobile
>
> Your complaint was that it is "located under screen border".  My reply is
> that what the "screen border" is is highly device specific and that  we
> don't cater to specific devices, therefore rejecting your complaint.  I
> never said "we don't support mobile".  That's it for me and this issue.
>

Well, at least now you know how I read the replies. Glad we settled this
down. Now it would be nice if somebody with CLA for docs could just move
this block upper.
History
Date User Action Args
2013-09-22 12:08:53techtoniksetmessages: + msg198270
2013-09-22 11:57:49georg.brandlsetmessages: + msg198268
2013-09-22 11:42:04techtoniksetmessages: + msg198266
2013-09-22 11:11:57georg.brandlsetmessages: + msg198259
2013-09-22 11:08:12techtoniksetmessages: + msg198258
2013-09-22 09:42:43python-devsetstatus: open -> closed

nosy: + python-dev
messages: + msg198253

resolution: fixed
stage: resolved
2013-09-22 09:42:36georg.brandlsetmessages: + msg198252
2013-09-22 09:21:51techtoniksetmessages: + msg198251
2013-09-22 08:45:26georg.brandlsetnosy: + georg.brandl

messages: + msg198250
versions: - Python 2.6, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5
2013-09-21 12:44:55techtoniksetmessages: + msg198195
2013-09-21 12:44:28techtonikcreate