Merge pull request #256 from alex/strong-docs

Explain ways in which we can make our docs stronger

1 files changed, 12 insertions, 0 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 3b301842..8e5b1ced 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -122,6 +122,18 @@ So, specifically:
 * No blank line at the end.
 * Use Sphinx parameter/attribute documentation `syntax`_.
 
+Because of the inherent challenges in implementing correct cryptographic
+systems, we want to make our documentation point people in the right directions
+as much as possible. To that end:
+
+* When documenting a generic interface, use a strong algorithm in examples.
+  (e.g. when showing a hashing example, don't use
+  :class:`cryptography.hazmat.primitives.hashes.MD5`)
+* When giving prescriptive advice, always provide references and supporting
+  material.
+* When there is real disagreement between cryptographic experts, represent both
+  sides of the argument and describe the tradeoffs clearly.
+
 When documenting a new module in the ``hazmat`` package, its documentation
 should begin with the "Hazardous Materials" warning: