<html><head></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; ">When updating the documentation, please don't go overboard with warnings.<div>The docs need to be worded affirmatively -- say what a tool does and show how to use it correctly.</div><div>See <a href="http://docs.python.org/documenting/style.html#affirmative-tone">http://docs.python.org/documenting/style.html#affirmative-tone</a></div><div><br></div><div>The docs for the subprocess module currently have SEVEN warning boxes on one page:</div><div><a href="http://docs.python.org/library/subprocess.html#module-subprocess">http://docs.python.org/library/subprocess.html#module-subprocess</a></div><div>The implicit message is that our tools are hazardous and should be avoided.</div><div><br></div><div>Please show some restraint and aim for clean looking, high-quality technical writing without the FUD.</div><div><br></div><div>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.</div><div><br></div><div><br></div><div>Raymond</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><div><br></div></div></body></html>