more minor design doc edits

2 files changed, 20 insertions, 21 deletions

diff --git a/docs/design/nicknym.md b/docs/design/nicknym.md
index ec6a1a9..009b285 100644
--- a/docs/design/nicknym.md
+++ b/docs/design/nicknym.md
@@ -5,15 +5,19 @@
 Introduction
 ==========================================
 
-Nicknym is a system to map user nicknames to public keys. With Nicknym, the user to be able to think solely in terms of nickname, while still being able to communicate with a high degree of security (confidentiality, integrity, and authenticity). Essentially, Nicknym is a system for binding human-memorable nicknames to a cryptographic key via automatic discovery and automatic validation.
+**What is Nicknym?**
+
+Nicknym is a protocol to map user nicknames to public keys. With Nicknym, the user is able to think solely in terms of nickname, while still being able to communicate with a high degree of security (confidentiality, integrity, and authenticity). Essentially, Nicknym is a system for binding human-memorable nicknames to a cryptographic key via automatic discovery and automatic validation.
 
 Nicknym is a federated protocol: a Nicknym address is in the form `username@domain` just alike an email address and Nicknym includes both a client and a server component. Although the client can fall back to legacy methods of key discovery when needed, domains that run the Nicknym server component enjoy much stronger identity guarentees.
 
 Nicknym is key agnostic, and supports whatever public key information is available for an address (OpenPGP, OTR, X.509, RSA, etc). However, Nicknym enforces a strict one-to-one mapping of address to public key.
 
-Existing forms of secure identity are deeply flawed. These systems rely on either a single trusted entity (e.g. Skype), a vulnerable Certificate Authority system (e.g. S/MIME), or keys that cannot be made human memorable (e.g. OpenPGP, OTR). When an identity system is hard to use, it is effectively compromised because too few people take the time to use it properly.
+**Why is Nicknym needed?**
+
+Existing forms of secure identity are deeply flawed. These systems rely on either a single trusted entity (e.g. Skype), a vulnerable Certificate Authority system (e.g. S/MIME), or key identifiers that are not human memorable (e.g. OpenPGP, OTR). When an identity system is hard to use, it is effectively compromised because too few people take the time to use it properly.
 
-The broken nature of existing identities systems (either in security or in usability) is especially troubling because identity remains a bedrock precondition for any message security: you cannot ensure confidentiality or integrity without confirming the authenticity of the other party. Nicknym is a protocol to solve this problem in a way that is backward compatible, easy for the user, and includes very strong authenticity when possible.
+The broken nature of existing identities systems (either in security or in usability) is especially troubling because identity remains a bedrock precondition for any message security: you cannot ensure confidentiality or integrity without confirming the authenticity of the other party. Nicknym is a protocol to solve this problem in a way that is backward compatible, easy for the user, and includes very strong authenticity.
 
 Goals
 ==========================================
@@ -40,19 +44,19 @@ Goals
 The binding problem
 =============================================
 
-Nicknym attempts to solve the problem of binding a human memorable identifer to a cryptographic key. If you have the identifier, you should be able to get the key with a high level of confidence, and vice versa. The goal is to have federated, human memorable, globally unique public keys. In other words, to somewhat violate [Zooko's triangle](https://en.wikipedia.org/wiki/Zooko's_triangle) by relying on the DNS system to partition a global namespace.
+Nicknym attempts to solve the problem of binding a human memorable identifer to a cryptographic key. If you have the identifier, you should be able to get the key with a high level of confidence, and vice versa. The goal is to have federated, human memorable, globally unique public keys.
 
 There are a number of established methods for binding identifier to key:
 
-* [Web of Trust (WOT)](http://en.wikipedia.org/wiki/Web_of_trust)
-* Trust on First Use (TOFU)
 * [X.509 Certificate Authority System](https://en.wikipedia.org/wiki/X.509)
+* Trust on First Use (TOFU)
+* Mail-back Verification
+* [Web of Trust (WOT)](http://en.wikipedia.org/wiki/Web_of_trust)
 * [DNSSEC](https://en.wikipedia.org/wiki/Dnssec)
 * [Shared Secret](https://en.wikipedia.org/wiki/Socialist_millionaire)
-* Mail-back Verification
 * [Network Perspective](http://convergence.io/)
-* Global Append-only Log
 * Nonverbal Feedback (a la ZRTP)
+* Global Append-only Log
 
 The methods differ widely, but they all try to solve the same general problem of proving that a person or organization is in control of a particular key.
 
diff --git a/docs/design/soledad.md b/docs/design/soledad.md
index d13fd9b..ab6544f 100644
--- a/docs/design/soledad.md
+++ b/docs/design/soledad.md
@@ -21,8 +21,7 @@ Soledad is an acronym of "Synchronization of Locally Encrypted Documents Among D
 Goals
 ======================
 
-Security goals
---------------------------------------
+**Security goals**
 
 * *Client-side encryption:* Before any data is synced to the cloud, it should be encrypted/decrypted on the client device.
 * *Encrypted local storage:* Any data cached or stored on the client should be stored in an encrypted format.
@@ -30,8 +29,7 @@ Security goals
 * *Resistant to online attacks:* Analysis of storing and retrieving data should not leak potentially sensitive information.
 * *Resistance to data tampering:* The server should not be able to provide the client with old or bogus data for a document.
 
-Synchronization goals
--------------------------------------
+**Synchronization goals**
 
 * *Consistency:* multiple clients should all get sync'ed with the same data.
 * *Sync flag:* the ability to partially sync data. For example, so a mobile device doesn't need to sync all email attachments.
@@ -40,20 +38,17 @@ Synchronization goals
 * *Scalable cloud:* distributed master-less storage on the cloud side, with no single point of failure.
 * *Conflict resolution:* conflicts are flagged and handed off to the application logic to resolve.
 
-Usability goals
----------------------------------
+**Usability goals**
 
 * *Availability*: the user should always be able to access their data.
 * *Recovery*: there should be a mechanism for a user to recover their data should they forget their password.
 
-Known limitations
-------------------------------
+**Known limitations**
 
 * Currently, the server knows when the contents of a document have changed.
 * Currently, there is no facility for sharing documents among multiple users.
 
-Non-goals
----------------------------
+**Non-goals**
 
 * Soledad is not for filesystem synchronization, storage or backup. It provides an API for application code to synchronize and store arbitrary schema-less JSON documents in one big flat document database. One could model a filesystem on top of Soledad, but it would be a bad fit.
 * Soledad is not intended for decentralized peer-to-peer synchronization, although the underlying synchronization protocol does not require a server. Soledad takes a cloud approach in order to ensure that a client has quick access to an available copy of the data.
@@ -65,7 +60,7 @@ Related software
 
 [U1DB](http://pythonhosted.org/u1db/) - Similar API as Soledad, without encryption.
 
-Protocol
+Soledad protocol
 ===================================
 
 Storage secret
@@ -231,7 +226,7 @@ TO DO: determine the response delay.
 TO DO: come up with a better abuse prevention scheme (maybe blind signature by the provider).
 TO DO: determine what HMAC to use.
 
-Client Reference Implementation
+Reference implementation of client
 ===================================
 
 Dependencies:
@@ -298,7 +293,7 @@ Synchronization-related classes:
   * `sync_exchange`: request encrypted version of Document's content before sending it to the network.
   * `_parse_sync_stream`: set Document's content based on encrypted version right after it arrives as a response from the network.
 
-Server Reference Implementation
+Reference implementation of server
 ======================================================
 
 Dependencies: