[Python-Dev] Warnings

[Georg Brandl]

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.

Georg