diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst
index c365d09d..5cc5ce82 100644
--- a/meta/documentation_style.rst
+++ b/meta/documentation_style.rst
@@ -1,43 +1,45 @@
-===================
 Documentation Style
 ===================
 
 A brief single sentence to describe what this file contains; in this case a
 description of the style to write documentation in.
 
+Format
+------
 
-Sections
-========
-
-Each section should be separated from the others by two blank lines. Headings
-should be underlined using a row of equals signs (===). Paragraphs should be
-separated by a single blank line, and wrap to no further than 80 columns.
+We use restructured text throughout all the documentation. You should NOT use
+markdown (github-flavored or otherwise). This format was chosen partly because
+Sphinx only supports RST.
 
-[[TODO(username): if you want to leave some unanswered questions, notes for
-further consideration, or other kinds of comment, use a TODO section. Make sure
-to notate it with your name so we know who to ask about it!]]
 
-Subsections
------------
+Sections
+--------
 
-If required, subsections can use a row of dashes to underline their header. A
-single blank line between subsections of a single section.
+RST support lots of different punctuation characters for underlines on sections.
+Content in the specification MUST use the same characters in order for the
+complete specification to be merged correctly. These characters are:
 
+- ``=`` : Top-level sections
+- ``-`` : Second-level sections
+- ``~`` : Third-level sections
+- ``+`` : Fourth-level sections
+- You should rethink your document layout if you require a fifth level.
 
-Bullet Lists
-============
+TODOs
+-----
 
- * Bullet lists can use asterisks with a single space either side.
- 
- * Another blank line between list elements.
+Any RST file in this repository may make it onto ``matrix.org``. We do not want
+``TODO`` markers visible there. For internal comments, notes, TODOs, use standard
+RST comments like so::
 
+  .. TODO-Bob
+    There is something to do here. This will not be rendered by something like
+    rst2html.py so it is safe to put internal comments here.
 
-Definition Lists
-================
+You SHOULD put your username with the TODO so we know who to ask about it.
 
-Terms:
-  Start in the first column, ending with a colon
+Line widths
+-----------
 
-Definitions:
-  Take a two space indent, following immediately from the term without a blank
-  line before it, but having a blank line afterwards.
+We use 80 characters for line widths. This is a guideline and can be flouted IF
+AND ONLY IF it makes reading more legible. Use common sense.