Give it up, Raymond. On Saturday, May 10, 2014, Raymond Hettinger <raymond.hettin...@gmail.com> wrote:
> > On May 10, 2014, at 2:54 PM, Antoine Pitrou > <solip...@pitrou.net<javascript:_e(%7B%7D,'cvml','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 > > -- --Guido van Rossum (on iPad)
_______________________________________________ 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
