Clarify TLS section

Also implement new Documentation section template.

Change-Id: Id7eb3ce2605102a1bf2e35b70a8c35324c0788c7

README.md

@@ -96,14 +96,17 @@ relation made to the vault application:
 
 ### Other applications
 
-Other applications can enable TLS by adding their own relation to Vault. Vault
+When Keystone is TLS-enabled every application that talks to Keystone (i.e.
-will issue certificates to the application and Keystone will update the
+there exists a relation between the two) must be in possession of the signing
-corresponding API endpoint from HTTP to HTTPS.
+CA cert. This is achieved by adding a relation between the application and
-
+Vault. Doing so will also encrypt the application's own endpoint. For example,
-For example, the Placement API:
+the Placement API:
 
     juju add-relation placement:certificates vault:certificates
 
+Vault will issue certificates to the application and Keystone will update the
+corresponding API endpoint from HTTP to HTTPS.
+
 > **Note**: API endpoints can be listed with `openstack catalog list`.
 
 ## Spaces
@@ -240,12 +243,18 @@ The below topics are covered in the [OpenStack Charms Deployment Guide][cdg].
   and tokens. It explains key rotation, and how to use the
   `fernet-max-active-keys` and `token-expiration` charm options.
 
+# Documentation
+
+The OpenStack Charms project maintains two documentation guides:
+
+* [OpenStack Charm Guide][cg]: for project information, including development
+  and support notes
+* [OpenStack Charms Deployment Guide][cdg]: for charm usage information
+
 # Bugs
 
 Please report bugs on [Launchpad][lp-bugs-charm-keystone].
 
-For general charm questions refer to the [OpenStack Charm Guide][cg].
-
 <!-- LINKS -->
 
 [hacluster-charm]: https://jaas.ai/hacluster