On May 10, 2014, at 2:54 PM, Antoine Pitrou <solip...@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
_______________________________________________ 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
