A handful of cleanups and rewordings to the docs
diff --git a/docs/contributing.rst b/docs/contributing.rst
index cb9c728..f176393 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -53,11 +53,10 @@
Most projects' APIs are designed with a philosophy of "make easy things easy,
and make hard things possible". One of the perils of writing cryptographic code
-is that code that is secure looks just like code that isn't, and produces
-results that are also difficult to distinguish. As a result ``cryptography``
-has, as a design philosophy: "make it hard to do insecure things". Here are a
-few strategies for API design which should be both followed, and should inspire
-other API choices:
+is that secure code looks just like insecure code, and it's results are almost
+always indistinguishable. As a result ``cryptography`` has, as a design
+philosophy: "make it hard to do insecure things". Here are a few strategies for
+API design which should be both followed, and should inspire other API choices:
If it is incorrect to ignore the result of a method, it should raise an
exception, and not return a boolean ``True``/``False`` flag. For example, a
@@ -163,7 +162,7 @@
* 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`)
+ :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
@@ -206,7 +205,7 @@
$ py.test
...
- 4294 passed in 15.24 seconds
+ 62746 passed in 220.43 seconds
This runs the tests with the default Python interpreter.
@@ -244,7 +243,8 @@
docs: commands succeeded
congratulations :)
-The HTML documentation index can now be found at ``docs/_build/html/index.html``
+The HTML documentation index can now be found at
+``docs/_build/html/index.html``.
.. _`GitHub`: https://github.com/pyca/cryptography