[Python-checkins] devguide: #13515: document security-related documentation practices.

[ezio.melotti]

http://hg.python.org/devguide/rev/8bb5f4301e01
changeset:   647:8bb5f4301e01
user:        Ezio Melotti <ezio.melotti at gmail.com>
date:        Mon Oct 21 03:14:07 2013 +0300
summary:
  #13515: document security-related documentation practices.

files:
  documenting.rst |  21 +++++++++++++++++++++
  1 files changed, 21 insertions(+), 0 deletions(-)


diff --git a/documenting.rst b/documenting.rst
--- a/documenting.rst
+++ b/documenting.rst
@@ -189,6 +189,27 @@
 text.  Long descriptions full of corner cases and caveats can create the
 impression that a function is more complex or harder to use than it actually is.
 
+Security Considerations (and Other Concerns)
+--------------------------------------------
+
+Some modules provided with Python are inherently exposed to security issues
+(e.g. shell injection vulnerabilities) due to the purpose of the module
+(e.g. :mod:`ssl`).  Littering the documentation of these modules with red
+warning boxes for problems that are due to the task at hand, rather than
+specifically to Python's support for that task, doesn't make for a good
+reading experience.
+
+Instead, these security concerns should be gathered into a dedicated
+"Security Considerations" section within the module's documentation, and
+cross-referenced from the documentation of affected interfaces with a note
+similar to ``"Please refer to the :ref:`security-considerations` section
+for important information on how to avoid common mistakes."``.
+
+Similarly, if there is a common error that affects many interfaces in a
+module (e.g. OS level pipe buffers filling up and stalling child processes),
+these can be documented in a "Common Errors" section and cross-referenced
+rather than repeated for every affected interface.
+
 Code Examples
 -------------
 

-- 
Repository URL: http://hg.python.org/devguide