diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index b9c668051..e3db28fd8 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -103,7 +103,7 @@ the ``newsfragments`` directory. The ``type`` can be one of the following: All news fragments must have a brief summary explaining the change in the contents of the file. The summary must end in a full stop to be in line with -the style guide and and formatting must be done using Markdown. +the style guide and formatting must be done using Markdown. Changes that do not change the spec, such as changes to the build script, formatting, CSS, etc should not get a news fragment. diff --git a/README.md b/README.md index a9d8dd9b2..deeb31f06 100644 --- a/README.md +++ b/README.md @@ -35,8 +35,8 @@ The Matrix spec is compiled with [Hugo](https://gohugo.io/) (a static site gener * `/themes`: you can use just Hugo or use it with a theme. Themes primarily provide additional templates, which are supplied in a `/themes/$theme_name/layouts` directory. You can use a theme but customise it by providing your own - versions of any of the them layouts in the base `/layouts` directory. That is, if a theme provides - `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of this + versions of any of the theme layouts in the base `/layouts` directory. That is, if a theme provides + `/themes/$theme_name/layouts/sidebar.html` and you provide `/layouts/sidebar.html`, then your version of the template will be used. It also has the following top-level file: @@ -51,7 +51,7 @@ Additionally, the following directories may be of interest: * `/event-schemas`: [JSON Schema](http://json-schema.org/) definitions for the spec. * `/data-definitions`: Bits of structured data consumable by Matrix implementations. * `/meta`: Documentation relating to the spec's processes that are otherwise untracked (release instructions, etc). -* `/scripts`: Various scripts for generating the spec. +* `/scripts`: Various scripts for generating the spec and validating its contents. * `/proposals`: Matrix Spec Change (MSC) proposals. See . * `/api`: [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) / Swagger definitions for the spec. @@ -64,7 +64,7 @@ place after an MSC has been accepted, not as part of a proposal itself. 1. Install the extended version (often the OS default) of Hugo: 2. Run `git submodule update --init --recursive` for good measure. 3. Run `npm i` to install the dependencies. Note that this will require NodeJS to be installed. -4. Run `npm run get-proposals` to seed the proposals data. This is not required. +4. Run `npm run get-proposals` to seed proposal data. This is merely for populating the content of the "Spec Change Proposals" page and is not required. 5. Run `hugo serve` to run a local webserver which builds whenever a file change is detected. If watching doesn't appear to be working for you, try `hugo serve --disableFastRender` instead. 6. Edit the specification 🙂 @@ -75,7 +75,7 @@ Awesome. If you're looking at making design-related changes to the spec site, pl ## Building the specification -If for some reason you're not a CI/CD system and want to render the spec yourself, follow the above steps for authoring +If for some reason you're not a CI/CD system and want to render a static version of the spec for yourself, follow the above steps for authoring changes to the specification and instead of `hugo serve` run `hugo -d "spec"` - this will generate the spec to `/spec`. If you'd like to serve the spec off a path instead of a domain root (eg: `/unstable`), add `--baseURL "/unstable"` to the `hugo -d "spec"` command. diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 5528f73e5..cfec5e3ba 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -8,7 +8,7 @@ in. Format ------ -Documentation is written either in github-flavored markdown. +Documentation is written in github-flavored markdown. Sections --------