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,27 +4,36 @@ 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.
-- ``event-schemas`` : Contains the `JSON Schema`_ for all Matrix events
+- ``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
+- ``meta``: Contains documents outlining the processes involved when writing
   documents, e.g. documentation style, guidelines.
-- ``scripts`` : Contains scripts to generate formatted versions of the
+- ``scripts``: Contains scripts to generate formatted versions of the
   documentation, typically HTML.
-- ``specification`` : Contains the specification split up into sections.
-- ``supporting-docs`` : Contains additional documents which explain design 
+- ``specification``: Contains the specification split up into sections.
+- ``supporting-docs``: Contains additional documents which explain design
   decisions, examples, use cases, etc.
-- ``templating`` : Contains the templates and templating system used to
+- ``templating``: Contains the templates and templating system used to
   generate the spec.
 
 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
 -----