diff --git a/docs/README.md b/docs/README.md
index b496cc6..22a3fd7 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,9 +1,9 @@
-# Defining Models for CORD
+# Modeling Guide
 
 CORD adopts a model-based design, which is to say all aspects
 of operating and managing CORD is mediated by a model-based
-control plane. XOS is the component in CORD that implements
-this control plane. For an overview of XOS, see the following
+control plane. XOS is a tool that CORD uses to implement this
+control plane. For an overview of XOS, see the following
 white paper:
 [XOS: Modeling-as-a-Service](https://wiki.opencord.org/display/CORD/XOS%3A+The+CORD+Controller?preview=/1279317/4981376/XOS%20Modeling-as-a-Service.pdf).
 
diff --git a/docs/core_models.md b/docs/core_models.md
index aecaba8..f3b2e7a 100644
--- a/docs/core_models.md
+++ b/docs/core_models.md
@@ -1,11 +1,12 @@
 # Core Models
 
-The XOS modeling framework provides a foundation for building CORD, but it is
-just a tool to defining a set of core models. It is these core models that
-provide a coherent interface for configuring, controlling, and applying policy
-to a CORD POD. This gives operators a way to specify and reason about the
-behavior of CORD, while allowing for a wide range of implementation choices for
-the underlying software components.
+The XOS modeling framework provides a foundation for building CORD,
+but it is just a tool used to define a set of core models. It is these
+core models that provide a coherent interface for configuring,
+controlling, and applying policy to a CORD POD. This gives operators a
+way to specify and reason about the behavior of CORD, while allowing
+for a wide range of implementation choices for the underlying software
+components.
 
 ## Services, Slices, and ServiceInstances
 
diff --git a/docs/dev/sync_arch.md b/docs/dev/sync_arch.md
index c647e86..6fe14bb 100644
--- a/docs/dev/sync_arch.md
+++ b/docs/dev/sync_arch.md
@@ -96,7 +96,7 @@
     * Read/Write Declarative state
     * Subscribe to changes to Declarative state
 
-## Relationships Between Synchronizers and Data Models
+## Relationships Between Synchronizers and Models
 
 A single synchronizer can synchronize multiple data models, usually through an
 actuator per model. However, a given model can only be handled by one actuator.
diff --git a/docs/dev/sync_reference.md b/docs/dev/sync_reference.md
index 4bab382..0cfe959 100644
--- a/docs/dev/sync_reference.md
+++ b/docs/dev/sync_reference.md
@@ -12,14 +12,14 @@
 `convenience_methods` can be defined in a folder (`convenience`) that needs to 
 be a child of the `models_dir` as per your configuration. 
 
-> For example if your configuration contains:
->
-> ```yaml 
-> models_dir: "/opt/xos/synchronizers/<synchronizer_name>/models"
-> ```
->
-> then you `convenience methods` needs to be located in 
-> `/opt/xos/synchronizers/<synchronizer_name>/models/convenience`
+For example if your configuration contains:
+
+```yaml 
+models_dir: "/opt/xos/synchronizers/<synchronizer_name>/models"
+```
+
+then you `convenience methods` needs to be located in 
+`/opt/xos/synchronizers/<synchronizer_name>/models/convenience`
 
 Assuming our model definition looks like:
 
diff --git a/docs/security_policies.md b/docs/security_policies.md
index c49496d..b6aa8e3 100644
--- a/docs/security_policies.md
+++ b/docs/security_policies.md
@@ -14,7 +14,7 @@
 auto-generated by the generative toolchain as part of the model generation
 process.
 
-> Note: Auditing is still todo.
+> **Note:** Auditing is still todo.
 
 Policies are generic logic expressions and can operate on any model or on the
 environment, but they frequently use the *Privilege* model.  Specifically, when