website: nit picking

website/source/docs/internals/architecture.html.md

@@ -15,22 +15,25 @@ build a mental model of how it works, this page documents the system architectur
 of Vault. You don't need to understand these details to
 effectively use Vault. The details are documented here for
 those who wish to learn about them without having to go
-spelunking through the source code.
+spelunking through the source code. However, if you're an
+operator of Vault, we recommend learning about the architecture
+due to the importance of Vault in an environment.
 
 # Glossary
 
-Before describing the architecture, we provide a glossary of terms to help clarify what is being discussed:
+Before describing the architecture, we provide a glossary of terms to help
+clarify what is being discussed:
 
-* Storage Backend - A storage backend is responsible for durable storage of _encrypted_ data.
+* **Storage Backend** - A storage backend is responsible for durable storage of _encrypted_ data.
   backends are not trusted by Vault and are only expected to provide durability. The storage
   backend is configured when starting the Vault server.
 
-* Barrier - The barrier is cryptographic steel and concrete around the Vault. All data that
+* **Barrier** - The barrier is cryptographic steel and concrete around the Vault. All data that
   flows between Vault and the Storage Backend passes through the barrier. The barrier ensures
   that only encrypted data is written out, and that data is verified and decrypted on the way
   in. Much like a bank vault, the barrier must be "unsealed" before anything inside can be accessed.
 
-* Secret Backend - A secret backend is responsible for managing secrets. Simple secret backends
+* **Secret Backend** - A secret backend is responsible for managing secrets. Simple secret backends
   like the "generic" backend simply return the same secret when queried. Some backends support
   using policies to dynamically generate a secret each time they are queried. This allows for
   unique secrets to be used which allows Vault to do fine-grained revocation and policy updates.
@@ -38,23 +41,23 @@ Before describing the architecture, we provide a glossary of terms to help clari
   is read, a new MySQL user/password pair will be generated with a limited set of privileges
   for the web server.
 
-* Audit Backend - An audit backend is responsible for managing audit logs. Every request to Vault
+* **Audit Backend** - An audit backend is responsible for managing audit logs. Every request to Vault
   and response from Vault goes through the configured audit backends. This provides a simple
   way to integrate Vault with multiple audit logging destinations of different types.
 
-* Credential Backend - A credential backend is used to authenticate users or applications which
+* **Credential Backend** - A credential backend is used to authenticate users or applications which
   are connecting to Vault. Once authenticated, the backend returns the list of applicable policies
   which shoud be applied. Vault takes an authenticated user and returns a client token that can
   be used for future requests. As an example, the `user-password` backend uses a username and password
   to authenticate the user. Alternatively, the `github` backend allows users to authenticate
   via GitHub.
 
-* Client Token - A client token is a conceptually similar to a session cookie on a web site.
+* **Client Token** - A client token is a conceptually similar to a session cookie on a web site.
   Once a user authenticates, Vault returns a client token which is used for future requests.
   The token is used by Vault to verify the identity of the client and to enforce the applicable
   ACL policies.
 
-* Secret - A secret is the term for anything returned by Vault which contains confidential
+* **Secret** - A secret is the term for anything returned by Vault which contains confidential
   or cryptographic material. Not all everything returned by Vault is a secret, for example
   system configuration, status information, or backend policies are not considered Secrets.
   Secrets always have an associated lease. This means clients cannot assume that the secret
@@ -63,7 +66,7 @@ Before describing the architecture, we provide a glossary of terms to help clari
   between Vault and it's clients is critical, as it allows for changes in keys and policies
   without manual intervention.
 
-* Server - Vault depends on a long-running instance which operates as a server.
+* **Server** - Vault depends on a long-running instance which operates as a server.
   The Vault server provides an API which clients interact with and manages the
   interaction between all the backends, ACL enforcement, and secret lease revocation.
   Having a server based architecture decouples clients from the security keys and policies,

website/source/docs/internals/index.html.md

@@ -13,4 +13,5 @@ details of how Vault functions, it's architecture and security properties.
 
 -> **Note:** Knowledge of Vault internals is not
 required to use Vault. If you aren't interested in the internals
-of Vault, you may safely skip this section.
+of Vault, you may safely skip this section. If you're operating Vault,
+we recommend understanding the internals.

website/source/layouts/docs.erb

@@ -11,9 +11,9 @@
 					<ul class="nav">
 						<li<%= sidebar_current("docs-internals-architecture") %>>
 							<a href="/docs/internals/architecture.html">Architecture</a>
-
-					</ul>
 						</li>
+					</ul>
+				</li>
 
 				<li<%= sidebar_current("docs-commands") %>>
 					<a href="/docs/commands/index.html">Commands (CLI)</a>