On Sat, 10 May 2014 14:35:38 -0700 Raymond Hettinger <raymond.hettin...@gmail.com> wrote: > > In the past couple of years, we've grown an unfortunate tendency > to fill the docs with big warning boxes (the subprocess docs are > an example of implicitly communicating that the module is dangerous > and unusable). > > The preferred form of documentation is to be affirmatively worded, > telling how to use a tool correctly and what its known limitations are. > We save the warnings for cases of actual danger where otherwise > well informed users get tripped-up. > > Tim Peters used to be around to articulate the principle that we don't write > the docs with the assumption that the users are less bright than we are > or that they can't read.
I agree with Alex. It's not about being bright or not, it's about being *willing* to eat walls of text. However pleasant it may be for some people to *write* documentation, for most readers (and especially non-native English readers, who read more slowly and more painfully than native ones), documentation is a piece of reference that they skim from, rather than read from start to end like a novel. So it makes sense to single out useful information. Knowing that the functions from the random module are not appropriate for cryptography is (IMO) more important than knowing that """Python uses the Mersenne Twister as the core generator. It produces 53-bit precision floats and has a period of 2**19937-1. The underlying implementation in C is both fast and threadsafe""" Regards Antoine. _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
