Latinisms (e.g., i.e., etc.) - should the docs style guide advise against them and suggest English phrases?
How do we feel about latinisms like i.e.
, e.g.
, etc? I haven't seen anything on this in any of the guides.
I've met many non-native English speakers who mixed their meanings, thinking for example that "i.e." means "in example", which made them to use it instead of "for example".
I propose a guideline like this:
Latinisms, such as i.e., e.g., or etc. can be vague and confusing to non-native speakers.
Instead, it's better to use English equivalents:
i.e -> that is
e.g. -> for example / such as / like
etc. -> and so on (or nothing, since it can be vague)
Marcia has raised a good point (below), so if implementing this, maybe introduce it as a guideline/best practice instead of a strict rule?
From the discussion in #docs-style
:
Russell:
My vote is that we should avoid them completely. I like your suggested replacements. IMO use of “etc” is lazy, and can often be replaced with “for example ….“.
Axil:
Agreed
🙂
Marcia:
I’m not very fond of restricting the guidelines too much, as it makes contributions much harder. We, TWs, are not the only contributors to the GL documentation; we have hundreds of contributors. We have kind of a “free style”, with rules mostly for syntax. The important thing is that the content is clear. Restricting this much is not beneficial, on the contrary, it makes harder and harder to contribute to content, and makes the reviews even more complicated.