Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Minor updates to documentation style #1456

Merged
merged 1 commit into from
Feb 28, 2023
Merged

Minor updates to documentation style #1456

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 26 additions & 20 deletions meta/documentation_style.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,33 +44,39 @@ Stylistic notes
General
~~~~~~~

Try to write clearly and unambiguously. Remember that many readers will not
have English as their first language.
* 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.
* Prefer British English (colour, -ise) to American English.

The word "homeserver" is spelt thus (rather than "home server", "Homeserver",
or (argh) "Home Server"). However, an identity server is two words.
* The word "homeserver" is spelt thus (rather than "home server", "Homeserver",
or (argh) "Home Server"). However, an identity server is two words.

An "identity server" (spelt thus) implements the Identity Service API (also spelt
thus). However, "Application Services" (spelt thus) implement the Application Service
API. Application Services should not be called "appservices" in documentation.
* An "identity server" (spelt thus) implements the Identity Service API (also spelt
thus). However, "Application Services" (spelt thus) implement the Application Service
API. Application Services should not be called "appservices" in documentation.

.. Rationale: "homeserver" distinguishes from a "home server" which is a server
you have at home. "identity server" is clear, whereas "identityserver" is
horrible.
.. Rationale: "homeserver" distinguishes from a "home server" which is a server
you have at home. "identity server" is clear, whereas "identityserver" is
horrible.

Lists should:
* Lists should:

* Be introduced with a colon.
* Be used where they provide clarity.
* Contain entries which start with a capital and end with a full stop.
* Be introduced with a colon.
* Be used where they provide clarity.
* Contain entries which start with a capital and end with a full stop.

When talking about properties in JSON objects, prefer the word "property" to "field",
"member", or various other alternatives. For example: "this property will be set to
X if ...". Also avoid the term "key" unless you are specifically talking about the
*name* of a property - and be mindful of the scope for confusion with cryptographic
keys.
* When talking about properties in JSON objects, prefer the word "property" to "field",
"member", or various other alternatives. For example: "this property will be set to
X if ...". Also avoid the term "key" unless you are specifically talking about the
*name* of a property - and be mindful of the scope for confusion with cryptographic
keys.

* "i.e." (*id est*) is an abbreviation and hence is written with two full
stops. Prefer full sentences where possible without loss of clarity.

* Prefer "for example" over "e.g.". If you *must* use "e.g.", remember it too
is an abbreviation (*exempli gratia*).
Comment on lines +75 to +79
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Carrying over some comments from #1424 (comment):

@turt2live says:

... I'm not currently convinced it's a thing we [should] do - given the first point is that the language should be unambiguous, shouldn't we be using complete words/sentences instead? ("For example", "As demonstrated below", "..., such as when", etc)

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree in principle, and certainly "for example" is generally preferable to "e.g". I have worded this accordingly.

i.e. is really handy and doesn't have a direct analogue: although its literal translation is "that is", you can't just switch that in and expect to keep the same meaning. The change that inspired this update to the doc style is https://github.com/matrix-org/matrix-spec/pull/1424/files#diff-7b8c1672b39828e4d12f305f5a3213c03f902c370bff42627eefb6a9b6f0c2eaR15-R17 and I'm struggling to think of ways to phrase that which are clear and convey the same thing.

In compromise, I have suggested a soft preference for full sentences.


Changes between spec versions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expand Down