[Python-Dev] Warnings

Georg Brandl g.brandl at gmx.net
Thu Dec 1 22:24:54 CET 2011

Am 01.12.2011 07:10, schrieb Raymond Hettinger:
> When updating the documentation, please don't go overboard with warnings.
> The docs need to be worded affirmatively -- say what a tool does and show how to
> use it correctly.
> See http://docs.python.org/documenting/style.html#affirmative-tone
> The docs for the subprocess module currently have SEVEN warning boxes on one page:
> http://docs.python.org/library/subprocess.html#module-subprocess
> The implicit message is that our tools are hazardous and should be avoided.
> Please show some restraint and aim for clean looking, high-quality technical
> writing without the FUD.
> Look at the SQLite3 docs for an example of good writing.  The prevention of SQL
> injection attacks is discussed briefly and effectively without big red boxes
> littering the page.

Obviously, +1.


More information about the Python-Dev mailing list