On Dec 1, 2011, at 1:10 AM, Raymond Hettinger wrote: > 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.
I'm not convinced this is actually a great example of how to outline pitfalls clearly; it doesn't say what an SQL injection attack is, or what the consequences might be. Also, it's not the best example of a positive tone. The narrative is: You probably want to do X. Don't do Y, because it will make you vulnerable to a Q attack. Instead, do Z. Here's an example of Y. Don't do it! Okay, finally, here's an example of Z. It would be better to say "You probably want to do X. Here's how you do X, with Z. Here's an example of Z." Then, later, discuss why some people want to do Y, and why you should avoid that impulse. However, what 'subprocess' is doing clearly isn't an improvement, it's not an effective introduction to secure process execution, just a reference document punctuated with ambiguous anxiety. sqlite3 is at least somewhat specific :). I think both of these documents point to a need for a recommended idiom for discussing security, or at least common antipatterns, within the Python documentation. I like the IETF's "security considerations" section, because it separates things off into a section that can be referred to later, once the developer has had an opportunity to grasp the basics. Any section with security implications can easily say "please refer to the 'security considerations' section for important information on how to avoid common mistakes" without turning into a big security digression on its own. -glyph
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
