Filip/matrix-spec
1
0
Fork 0
mirror of https://github.com/matrix-org/matrix-spec synced 2026-04-29 13:54:10 +02:00
Code Issues Actions 3 Packages Projects Releases Wiki Activity

Merge 10a277b77e into 9fd3c00086

Browse source
This commit is contained in:
Richard van der Hoff 2026-04-28 19:01:25 +01:00 committed by GitHub
parent 9fd3c00086 10a277b77e
commit 116a0ed2a0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 17 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
changelogs/internal/newsfragments/2366.clarification Normal file
View file

@ -0,0 +1,2 @@
Clarify use of UK vs US English in documentation style doc.

17
meta/documentation_style.rst
View file

@ -19,7 +19,7 @@ nested titles (h6, or 6 `#` characters) and instead re-evaluate the document str
Correct capitalisation for long section names
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Headings should be in `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`,
Headings should be in `sentence case <https://apastyle.apa.org/style-grammar-guidelines/capitalization/sentence-case>`_,
as represented by this document.
TODOs
@ -47,7 +47,20 @@ General
* Try to write clearly and unambiguously. Remember that many readers will not
have English as their first language.
* Prefer British English (colour, -ise) to American English.
* The Matrix spec uses British English rather than American English. For example, the
words "colour" and "authorise" use British spellings. The
``join_authorised_via_users_server`` property in ``m.room.member`` events is
spelt accordingly.
* This extends to terms defined in other specifications: for example, in the
context of OAuth 2.0, we refer to an "authorisation code grant", even though
RFC6749 uses the spelling "authorization".
Of course, identifiers used within the protocol itself must use the
spellings defined by the protocol. So, for example, the
``authorization_endpoint`` property in the `OAuth 2.0
metadata <https://spec.matrix.org/v1.18/client-server-api/#get_matrixclientv1auth_metadata>`_
uses the same spelling as defined in `RFC8414 <https://www.rfc-editor.org/rfc/rfc8414#section-2>`_.
* The word "homeserver" is spelt thus (rather than "home server", "Homeserver",
or (argh) "Home Server"). However, an identity server is two words.