fixed nits
Change-Id: Ia1b718d55900f87197a9787b362979f57ec9d13e
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