On May 10, 2014, at 2:54 PM, Antoine Pitrou firstname.lastname@example.org 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.)
Those docs are clear, concise, not preachy, and not littered with distractions.