From be036f1c8f116d9aa0db1bc0a40dd2dad10de696 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 28 Apr 2026 16:37:42 +0100 Subject: [PATCH 1/4] Clarify our stance on en_GB vs en_US --- .../internal/newsfragments/2366.clarification | 2 ++ meta/documentation_style.rst | 15 ++++++++++++++- 2 files changed, 16 insertions(+), 1 deletion(-) create mode 100644 changelogs/internal/newsfragments/2366.clarification diff --git a/changelogs/internal/newsfragments/2366.clarification b/changelogs/internal/newsfragments/2366.clarification new file mode 100644 index 00000000..8f6e810f --- /dev/null +++ b/changelogs/internal/newsfragments/2366.clarification @@ -0,0 +1,2 @@ +Clarify use of UK vs US English in documentation style doc. + diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index afb5ff98..c1e9384c 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -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 "authori**s**ation code grant", even though + RFC6749 uses the spelling "authori**z**ation". + + 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. * The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity server is two words. From f77a59d76d68eee2c6f8e195e2207f13c47eb08f Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 28 Apr 2026 16:46:12 +0100 Subject: [PATCH 2/4] Fix RST formatting --- meta/documentation_style.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index c1e9384c..620b9ef2 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -53,13 +53,13 @@ General spelt accordingly. * This extends to terms defined in other specifications: for example, in the - context of OAuth 2.0, we refer to an "authori**s**ation code grant", even though - RFC6749 uses the spelling "authori**z**ation". + 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) + `authorization_endpoint` property in the `OAuth 2.0 + metadata ` uses the same spelling as defined in RFC8414. * The word "homeserver" is spelt thus (rather than "home server", "Homeserver", From 022d0b3a0daf9d0ae77bb9c615ddc6e69f66d58c Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 28 Apr 2026 16:53:11 +0100 Subject: [PATCH 3/4] fix links --- meta/documentation_style.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 620b9ef2..f8946b9e 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -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 `, +Headings should be in `sentence case `_, as represented by this document. TODOs @@ -59,7 +59,7 @@ General 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 ` + metadata `_ uses the same spelling as defined in RFC8414. * The word "homeserver" is spelt thus (rather than "home server", "Homeserver", From 10a277b77e32cf24c693d24bec945370c1bf65c7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> Date: Tue, 28 Apr 2026 19:01:21 +0100 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Andrew Morgan <1342360+anoadragon453@users.noreply.github.com> Co-authored-by: Richard van der Hoff <1389908+richvdh@users.noreply.github.com> --- meta/documentation_style.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index f8946b9e..e6b83249 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -49,7 +49,7 @@ General * 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 + ``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 @@ -58,9 +58,9 @@ General 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 + ``authorization_endpoint`` property in the `OAuth 2.0 metadata `_ - uses the same spelling as defined in RFC8414. + uses the same spelling as defined in `RFC8414 `_. * The word "homeserver" is spelt thus (rather than "home server", "Homeserver", or (argh) "Home Server"). However, an identity server is two words.