[docs] [issue13515] Consistent documentation practices for security concerns and considerations

[Ezio Melotti]

Ezio Melotti <ezio.melotti at gmail.com> added the comment:

I think we are mixing a few different things here:
1) the content of the warning(s);
2) the position of the warning(s);
3) the style of the warning(s);

Duplicating the same content in each warning is bad, so a specific section that summarizes the problem is good.
Having at least a note with a link to the "Security consideration" section in each affected function is good too, because without them people won't notice it.
Having big red scary boxes is bad, because people are scared of big red things (especially scary ones), and our goal here is to warn, not to scare.

I think the problem with the subprocess doc is that there are many warnings and that they are big and red (and scary).  IMHO changing the style of the warning would already be a step forward the "clean look" advocated by Raymond.  Grouping redundant text and possibly rephrasing it a bit would do the rest.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue13515>
_______________________________________