Minor updates to documentation style #1456
Conversation
i.e. has full-stops
| * "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*). |
There was a problem hiding this comment.
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)
There was a problem hiding this comment.
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.
i.e. has full-stops
i.e. has full-stops
Preview: https://pr1456--matrix-spec-previews.netlify.app