Merge pull request #328 from alex/docs-cleanups

A handful of cleanups and rewordings to the docs

1 files changed, 8 insertions, 8 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index cb9c7283..b1702df8 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -53,11 +53,10 @@ API Considerations
 
 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 its 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 @@ 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`)
+  :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 @@ automatically, so all you have to do is:
 
    $ 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 @@ Use `tox`_ to build the documentation. For example:
    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