Improved the docs -- more glossary entries, more advice for writing docs

2 files changed, 14 insertions, 0 deletions

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 97f31e0b..4647818a 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -141,6 +141,9 @@ should begin with the "Hazardous Materials" warning:
 
     .. hazmat::
 
+When referring to a hypothetical individual (such as "a person receiving an
+encrypted message") use gender neutral pronouns (they/them/their).
+
 Development Environment
 -----------------------
 
diff --git a/docs/glossary.rst b/docs/glossary.rst
index b6f2d06f..63e0a6ce 100644
--- a/docs/glossary.rst
+++ b/docs/glossary.rst
@@ -28,3 +28,14 @@ Glossary
     asymmetric cryptography
         Cryptographic operations where encryption and decryption use different
         keys. There are separate encryption and decryption keys.
+
+    authentication
+        The process of verifying that a message was created by a specific
+        individual (or program). Like encryption, authentication can be either
+        symmetric or asymmetric. Authentication is necessary for effective
+        encryption.
+
+    Ciphertext indistinguishability
+        This is a property of encryption systems whereby two encrypted messages
+        aren't distinguishable without knowing the encryption key. This is
+        considered a basic, necessary property for a working encryption system.