Merge branch 'master' into release/client-server/r0.2.0

CONTRIBUTING.rst

@@ -87,6 +87,9 @@ matrix-doc should be based on the ``master`` branch.)
 Code style
 ~~~~~~~~~~
 
+The documentation style is described at
+https://github.com/matrix-org/matrix-doc/blob/master/meta/documentation_style.rst.
+
 Python code within the ``matrix-doc`` project should follow the same style as
 synapse, which is documented at
 https://github.com/matrix-org/synapse/tree/master/docs/code_style.rst.

README.rst

@@ -4,8 +4,14 @@ Structure
 =========
 
 - ``api`` : Contains the HTTP API specification.
-- ``drafts`` : Contains documents which will make it into the specification
-  and/or supporting documentation at some point in the future.
+- ``attic``: Contains historical sections of specification for reference
+  purposes.
+- ``changelogs``: Contains change logs for the various parts of the
+  specification.
+- ``drafts``: Previously, contained documents which were under discussion for
+  future incusion into the specification and/or supporting documentation. This
+  is now historical, as we use separate discussion documents (see
+  `<CONTRIBUTING.rst>`_).
 - ``event-schemas``: Contains the `JSON Schema`_ for all Matrix events
   contained in the specification, along with example JSON files.
 - ``meta``: Contains documents outlining the processes involved when writing
@@ -22,9 +28,12 @@ Contributing
 ============
 
 Known issues with the specification are represented as JIRA issues at
-https://matrix.org/jira/browse/SPEC
+`<https://matrix.org/jira/browse/SPEC>`_.
 
-If you want to ask more about the specification, or have suggestions for
-improvements, join us on ``#matrix-dev:matrix.org`` via https://matrix.org/beta.
+If you want to ask more about the specification, join us on
+`#matrix-dev:matrix.org <http://matrix.to/#/#matrix-dev:matrix.org>`_.
+
+If you would like to contribute to the specification or supporting
+documentation, see `<CONTRIBUTING.rst>`_.
 
 .. _JSON Schema: http://json-schema.org/

meta/documentation_style.rst

@@ -19,11 +19,17 @@ 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.
+- ``=``
+- ``-``
+- ``~``
+- ``+``
+- ``^``
+- `````
+- ``@``
+- ``:``
+
+If you find yourself using ``^`` or beyond, you should rethink your document
+layout if possible.
 
 TODOs
 -----