diff --git a/bigchaindb/common/schema/vote.yaml b/bigchaindb/common/schema/vote.yaml
index 8a09a10a..1cd602a1 100644
--- a/bigchaindb/common/schema/vote.yaml
+++ b/bigchaindb/common/schema/vote.yaml
@@ -25,12 +25,12 @@ properties:
     type: "string"
     pattern: "[1-9a-zA-Z^OIl]{86,88}"
     description:
-        Ed25519 signature of the ``vote`` object.
+        Ed25519 signature of the `Vote Details`_ object.
   vote:
     type: "object"
     additionalProperties: false
     description: |
-        Vote details to be signed.
+        `Vote Details`_ to be signed.
     required:
     - invalid_reason
     - is_block_valid
@@ -41,12 +41,12 @@ properties:
       previous_block:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
-          Sha3 identifier of the block that preceeds the block being voted on.
+          SHA3 identifier of the block that preceeds the block being voted on.
           The notion of a "previous" block is subject to vote.
       voting_for_block:
         "$ref": "#/definitions/sha3_hexdigest"
         description: |
-          Sha3 identifier of the block being voted on.
+          SHA3 identifier of the block being voted on.
       is_block_valid:
         type: "boolean"
         description: |
@@ -56,6 +56,10 @@ properties:
         - type: "string"
           description: |
             Reason the block is voted invalid, or ``null``.
+
+            .. container:: notice
+
+              **Note**: The invalid_reason was not being used and may be dropped in a future version of BigchainDB. See Issue `#217 <https://github.com/bigchaindb/bigchaindb/issues/217>`_ on GitHub.
         - type: "null"
       timestamp:
         type: "string"
diff --git a/docs/server/generate_schema_documentation.py b/docs/server/generate_schema_documentation.py
index 704157f3..2c850580 100644
--- a/docs/server/generate_schema_documentation.py
+++ b/docs/server/generate_schema_documentation.py
@@ -35,6 +35,15 @@ TPL_STYLES = """
          font-size: 100%%;
          font-family: monospace;
     }
+    .document .section p {
+        margin-bottom: 16px;
+    }
+    .notice {
+        margin: 0px 16px 16px 16px;
+        background-color: white;
+        border: 1px solid gold;
+        padding: 3px 6px;
+    }
     </style>
 """
 
diff --git a/docs/server/source/data-models/index.rst b/docs/server/source/data-models/index.rst
index 70a4fae4..86b62121 100644
--- a/docs/server/source/data-models/index.rst
+++ b/docs/server/source/data-models/index.rst
@@ -16,4 +16,4 @@ This section unpacks each one in turn.
    asset-model
    crypto-conditions
    block-model
-   vote-model
+   The Vote Model <../schema/vote>
diff --git a/docs/server/source/data-models/vote-model.md b/docs/server/source/data-models/vote-model.md
deleted file mode 100644
index dc2b6ae4..00000000
--- a/docs/server/source/data-models/vote-model.md
+++ /dev/null
@@ -1,19 +0,0 @@
-# The Vote Model
-
-A vote has the following structure:
-
-```json
-{
-    "node_pubkey": "<the public key of the voting node>",
-    "vote": {
-        "voting_for_block": "<id of the block the node is voting for>",
-        "previous_block": "<id of the block previous to this one>",
-        "is_block_valid": "<true|false>",
-        "invalid_reason": "<None|DOUBLE_SPEND|TRANSACTIONS_HASH_MISMATCH|NODES_PUBKEYS_MISMATCH",
-        "timestamp": "<Unix time when the vote was generated, provided by the voting node>"
-    },
-    "signature": "<signature of vote>"
-}
-```
-
-Note: The `invalid_reason` was not being used and may be dropped in a future version of BigchainDB. See [Issue #217](https://github.com/bigchaindb/bigchaindb/issues/217) on GitHub.
diff --git a/docs/server/source/schema/vote.rst b/docs/server/source/schema/vote.rst
index 98bed941..312e1973 100644
--- a/docs/server/source/schema/vote.rst
+++ b/docs/server/source/schema/vote.rst
@@ -29,7 +29,7 @@ Vote.signature
 
 **type:** string
 
-Ed25519 signature of the ``vote`` object.
+Ed25519 signature of the `Vote Details`_ object.
 
 
 Vote.vote
@@ -37,7 +37,7 @@ Vote.vote
 
 **type:** object
 
-Vote details to be signed.
+`Vote Details`_ to be signed.
 
 
 
@@ -46,7 +46,7 @@ Vote details to be signed.
 Vote Details
 ------------
 
-Vote details to be signed.
+`Vote Details`_ to be signed.
 
 
 Vote.previous_block
@@ -54,7 +54,7 @@ Vote.previous_block
 
 **type:** string
 
-Sha3 identifier of the block that preceeds the block being voted on.
+SHA3 identifier of the block that preceeds the block being voted on.
 The notion of a "previous" block is subject to vote.
 
 
@@ -64,7 +64,7 @@ Vote.voting_for_block
 
 **type:** string
 
-Sha3 identifier of the block being voted on.
+SHA3 identifier of the block being voted on.
 
 
 
@@ -84,6 +84,10 @@ Vote.invalid_reason
 
 Reason the block is voted invalid, or ``null``.
 
+.. container:: notice
+
+  **Note**: The invalid_reason was not being used and may be dropped in a future version of BigchainDB. See Issue `#217 <https://github.com/bigchaindb/bigchaindb/issues/217>`_ on GitHub.
+
 
 
 Vote.timestamp
@@ -115,4 +119,13 @@ to the system time of the node.
          font-size: 100%;
          font-family: monospace;
     }
+    .document .section p {
+        margin-bottom: 16px;
+    }
+    .notice {
+        margin: 0px 16px 16px 16px;
+        background-color: white;
+        border: 1px solid gold;
+        padding: 3px 6px;
+    }
     </style>