update introductory text

scripts/proposals.py

@@ -47,7 +47,7 @@ for label in labels:
 
 text_file = open("../specification/proposals.rst", "w")
 
-text_file.write("Tables\n------------------\n\n")
+text_file.write("Tables of Tracked Proposals\n---------------------------\n\n")
 
 
 for label in labels:

specification/proposals_intro.rst

@@ -3,24 +3,13 @@
 
 Proposals for Spec Changes to Matrix
 ------------------------------------
+The process for submitting a Matrix Spec Change (MSC) Proposal is as follows:
 
+- produce a publicly-accessible Google Doc describing you change
+- make a new issue at https://github.com/matrix-org/matrix-doc/issues with the metadata appropriate to the section below
+- make a new PR which includes the proposed changed at https://github.com/matrix-org/matrix-doc/tree/master/specification
 
-Proposal Tracking
------------------
-
-This is a living document generated from the list of proposals at `matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues?page=1&q=is%3Aissue+is%3Aopen>`_ on GitHub.
-
-We use labels and some metadata in the issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram below, these labels already exist in the matrix-doc repo.
-
-Other metadata:
-
-- the MSC (Matrix Spec Change) number is taken from the github issue ID. This is carried for the lifetime of the proposal, including the PR creation phase.
-- Please use the github issue title to set the title.
--  The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text.
-- Updated Date is taken from github.
-- Author is the creator of the github issue, but can be overriden by adding a "Author: @username" line in the body of the issue text. Please make sure @username is a github user (include the @!)
-- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user.
-
+The process for handling proposals is described in the following diagram. Note that there are corresponding labels for each stage available in the matrix-doc issue tracker.
 
 ::
 
@@ -65,4 +54,18 @@ Other metadata:
                          |                            |
                          +                            +
 
+Proposal Tracking
+-----------------
+
+This is a living document generated from the list of proposals at `matrix-doc/issues <https://github.com/matrix-org/matrix-doc/issues?page=1&q=is%3Aissue+is%3Aopen>`_ on GitHub.
+
+We use labels and some metadata in the issue text to generate this page. When adding or updating an issue, make sure you specify the current status as a label per the diagram above, these labels already exist in the matrix-doc repo.
+
+Other metadata:
 
+- the MSC (Matrix Spec Change) number is taken from the github issue ID. This is carried for the lifetime of the proposal, including the PR creation phase.
+- Please use the github issue title to set the title.
+-  The created date is taken from the github issue, but can be overriden by adding a "Date: yyyy-mm-dd" line in the body of the issue text.
+- Updated Date is taken from github.
+- Author is the creator of the github issue, but can be overriden by adding a "Author: @username" line in the body of the issue text. Please make sure @username is a github user (include the @!)
+- Shepherd is set by adding a "Shepherd: @username" line in the body of the issue text. Again, make sure this is a real Github user.