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..e6b83249 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 @@ -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 `_ + 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.