[Python-Dev] Warnings

[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.


Raymond






-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20111130/943b6f09/attachment-0001.html>