[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#40011: Remove unnecessary abbreviations from documentation
From: |
Stefan Kangas |
Subject: |
bug#40011: Remove unnecessary abbreviations from documentation |
Date: |
Tue, 10 Mar 2020 14:54:25 +0100 |
X-Debbugs-CC: Richard Stallman <rms@gnu.org>
Writing for Computer Science (2004) by Justin Zobel says:
"It is often tempting to use abbreviations such as 'no.', 'i.e.',
'e.g.' 'c.f.' and 'w.r.t.' These save little space on the page,
but slow readers down. It is almost always desirable to expand
these abbreviations, to 'number', 'that is', 'for example',
'compared with' (or more accurately 'in contrast to', since that
is the sense in which 'c.f.' should be used), and 'with respect
to', or synonyms of these expressions. Where such abbreviations
are used, the punctuation should be as if the expanded form were
used. Also consider expanding abbreviations such as 'Fig.' and
'Alg.' and don't use concoctions such as '1st' or '2nd'. Months
should not be abbreviated. Make sure that all abbreviations and
acronyms are explained when they are first used." (page 57)
Please consider removing the following acronyms from the
documentation, both the manual(s) and doc strings:
1. no. ("number")
2. e.g. ("for example")
3. i.e. ("that is", "namely", etc.)
4. c.f. ("in contrast to", "compared with", etc.)
5. w.r.t. ("with respect to")
Please also consider adding a guideline to avoid them where possible.
I think we should not do this in a blanket fashion, however, but treat
each case individually. For example, it seems to me that it's a good
idea to be much more lenient in tables, where space may be a serious
concern.
If anyone has any suggestions for other abbreviations that could
perhaps be avoided, please add them to the list. Any comments?
Best regards,
Stefan Kangas
PS. For further background, see Bug#39778:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=39778
- bug#40011: Remove unnecessary abbreviations from documentation,
Stefan Kangas <=