Give it up, Raymond. 

On Saturday, May 10, 2014, Raymond Hettinger <raymond.hettinger@gmail.com> wrote:

On May 10, 2014, at 2:54 PM, Antoine Pitrou <solipsis@pitrou.net> wrote:

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.

Most users of the random module documentation are just
normal people trying to create random numbers.  People
writing secure apps with cryptographically secure random
numbers are not the primary audience.  But we have this
big red security warning that essentially says, if you read
only one thing, read this.

Before proceeding further with stamping distracting security
warnings all over the module documentation, we should look
to other languages to see what others have found necessary.
This warning does not appear anywhere else I've looked 
(MS Excel docs, Java docs, Go lang docs, etc.)

http://docs.oracle.com/javase/6/docs/api/java/util/Random.html
http://golang.org/pkg/math/rand/

Those docs are clear, concise, not preachy, and not littered
with distractions.


Raymond



--
--Guido van Rossum (on iPad)