[docs] [issue17006] Add advice on best practices for hashing secrets

[Ezio Melotti]

Ezio Melotti added the comment:

> People are going to skip warning boxes if they occur too often.

I'm not sure I agree.  This would be true if they were abused for trivial things ("Warnings: using .pop() on a empty list will return an IndexError!"), but I don't think they are.

I think warnings are ignored only by people that are already familiar with the module and its limitation/issues, and that know what they are doing.  If the warning is not evident, people are going to miss it [0].

If warnings are used correctly, people will spot them easily and read them (or ignore them if they already know what they are warning against).

[0]: I know I missed it in e.g. https://api.jquery.com/die/ -- the function is deprecated, but (currently) this is only written in the top right corner and in small in the category at the top -- two places that are easily overlooked.  https://api.jquery.com/toggle-event/ on the other hand has a clearly visible yellow box at the top that immediately says that the method is deprecated.

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue17006>
_______________________________________