From e9d64d78b240d7e8c55ed6e04b0387e6666a6038 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 10:28:01 -0800 Subject: Explain ways in which we can make our docs stronger --- docs/contributing.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 3b301842..98578ee2 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 inherit 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 perscriptive advice, always provide references and supporting + material. +* When there is disagreement about legitimate 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: -- cgit v1.2.3 From 5cbab0c815681cff4bdbfde151953df2242ee7c9 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 11:55:57 -0800 Subject: typo fix --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 98578ee2..108ecb6a 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -129,7 +129,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`) -* When giving perscriptive advice, always provide references and supporting +* When giving prescriptive advice, always provide references and supporting material. * When there is disagreement about legitimate cryptographic experts, represent both sides of the argument and describe the tradeoffs clearly. -- cgit v1.2.3 From d118c91cc381ce757a6b14f4e4c60505c1cdb48a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 11:56:49 -0800 Subject: Clearer! --- docs/contributing.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index 108ecb6a..b86faaa1 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -131,8 +131,8 @@ as much as possible. To that end: :class:`cryptography.hazmat.primitives.hashes.MD5`) * When giving prescriptive advice, always provide references and supporting material. -* When there is disagreement about legitimate cryptographic experts, represent - both sides of the argument and describe the tradeoffs clearly. +* 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: -- cgit v1.2.3 From a659688c5de3c778eb175d0c3eae1db9a2e513a0 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Wed, 13 Nov 2013 12:54:03 -0800 Subject: typo --- docs/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/contributing.rst') diff --git a/docs/contributing.rst b/docs/contributing.rst index b86faaa1..8e5b1ced 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -122,7 +122,7 @@ So, specifically: * No blank line at the end. * Use Sphinx parameter/attribute documentation `syntax`_. -Because of the inherit challenges in implementing correct cryptographic +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: -- cgit v1.2.3