Reorganize spec index.

specification/index.rst

@@ -6,45 +6,43 @@ Matrix Specification
 .. have should hopefully not get complex enough that we need to worry about
 .. versioning it.
 
-This specification has been generated from
+Matrix is a set of APIs for open-federated Instant Messaging (IM), Voice
-https://github.com/matrix-org/matrix-doc using
+over IP (VoIP) and Internet of Things (IoT) communication, designed to create
-https://github.com/matrix-org/matrix-doc/blob/master/scripts/gendoc.py as of
+and support a new global real-time communication ecosystem.
-revision ``{{git_version}}`` -
-https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}.
 
-There is an `introduction and overview to the specification here <intro.html>`_.
+For a more complete introduction to Matrix, see `Introduction <intro.html>`_.
+
+Matrix APIs
+-----------
 
 The following APIs are documented in this specification:
 
-- `Client-Server API <client_server.html>`_ version %CLIENT_RELEASE_LABEL% for writing Matrix clients.
+- `Client-Server API <client_server.html>`_ (%CLIENT_RELEASE_LABEL%) Interaction between clients and servers
-- `Server-Server API <server_server.html>`_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix.
+- `Server-Server API <server_server.html>`_ (%SERVER_RELEASE_LABEL%) Federation between servers
-- `Application Service API <application_service.html>`_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers.
+- `Application Service API <application_service.html>`_ (%CLIENT_RELEASE_LABEL%) Privileged server plugins
-- `Identity Service API <identity_service.html>`_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs.
+- `Identity Service API <identity_service.html>`_ (unstable) Mapping of third party IDs with Matrix IDs
-- `Push Gateway API <push_gateway.html>`_ version unstable for implementing a server that receives notifications about Matrix events a user is interested in.
+- `Push Gateway API <push_gateway.html>`_ (unstable) Push notifications for Matrix events
 
-There are also some `appendices <appendices.html>`_.
+`Appendices <appendices.html>`_ with supplemental information not specific to
+of the above APIs is also available.
 
-Any developments since the latest release can be found `here`__.
+Specification Version
+---------------------
 
-.. __: https://matrix.org/speculator/spec/head/
+The documents in the specification are generated from
+`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
+`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
 
-Old releases of the spec:
+The following other versions of the specification are also available,
+in reverse chronological order:
 
+- `HEAD <https://matrix.org/speculator/spec/head/>`_: Includes all changes since the latest versioned release.
 - `r0.0.1 <https://matrix.org/docs/spec/r0.0.1>`_
 - `r0.0.0 <https://matrix.org/docs/spec/r0.0.0>`_
+- `Legacy <https://matrix.org/docs/spec/legacy/>`_: The last draft before the spec was formally released in version r0.0.0.
 
-Before we formally started releasing the specification, the last working copy
+The specification for each API is versioned in the form ``rX.Y.Z``. Changes to
-we had can be found `here`__.
+``X`` and ``Y`` should not be assumed to be compatible with any other version.
-
+For a fixed ``X`` and ``Y``, any ``Z`` should be assumed to be compatible with
-.. __: https://matrix.org/docs/spec/legacy/
+any lesser ``Z``. For example, it is safe to assume that a server which claims
-
+to implement ``r0.1.2`` supports ``r0.1.0``, but not vice-versa.
-Versioning
-----------
-
-The specifications are each versioned in the form ``rX.Y.Z``.
-
-Changes to ``X`` and ``Y`` should not be assumed to be compatible with any other version.
-
-For a fixed ``X`` and ``Y``, any ``Z`` should be assumed to be compatible with any lesser ``Z``.
-
-For example, it is safe to assume that a server which claims to implement ``r0.1.2`` supports ``r0.1.0``, but not vice-versa.