bug#40011: Remove unnecessary abbreviations from documentation

bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas]

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

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Date: Tue, 10 Mar 2020 14:54:25 +0100
> Cc: richard stallman <rms@gnu.org>
> 
> 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")

Let's not be too extreme: I'm against removing "e.g." and "i.e." at
the least.

bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 675 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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")
>
> Let's not be too extreme: I'm against removing "e.g." and "i.e." at
> the least.

There are many such instances to get right, so maybe we can find a way
forward which avoids changing all of them.

How about adding something along the lines of the attached patch, and
leave it at that?  Would that be acceptable?

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Recommend-avoiding-unnecessary-abbreviations-in-doc.patch --]
[-- Type: text/x-diff, Size: 1144 bytes --]

From a44c03f6a2b2b98b34b4c7836e3291fd2c458190 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Mon, 27 Apr 2020 07:53:10 +0200
Subject: [PATCH] Recommend avoiding unnecessary abbreviations in doc

* doc/lispref/tips.texi (Documentation Tips): Recommend avoiding
unnecessary abbreviations.  (Bug#40011)a
---
 doc/lispref/tips.texi | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 3b8da35b6c..382e6d7c61 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -820,6 +820,12 @@ Documentation Tips
 most cases, the meaning is clear with just ``if''.  Otherwise, try to
 find an alternate phrasing that conveys the meaning.
 
+@item
+Avoid abbreviations like ``e.g.'' (for ``for example''), ``i.e.'' (for
+``that is''), ``no.'' (for ``number''), ``c.f.'' (for ``in contrast
+to'') and ``w.r.t.'' (for ``with respect to'').  It is almost always
+both more clear and easier to read the expanded version.
+
 @item
 When a command is meaningful only in a certain mode or situation,
 do mention that in the documentation string.  For example,
-- 
2.26.2

bug#40011: Remove unnecessary abbreviations from documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 40011@debbugs.gnu.org,  rms@gnu.org
> Date: Mon, 27 Apr 2020 08:05:34 +0200
> 
> > Let's not be too extreme: I'm against removing "e.g." and "i.e." at
> > the least.
> 
> There are many such instances to get right, so maybe we can find a way
> forward which avoids changing all of them.
> 
> How about adding something along the lines of the attached patch, and
> leave it at that?  Would that be acceptable?
>  [...]
> +@item
> +Avoid abbreviations like ``e.g.'' (for ``for example''), ``i.e.'' (for
> +``that is''), ``no.'' (for ``number''), ``c.f.'' (for ``in contrast
> +to'') and ``w.r.t.'' (for ``with respect to'').  It is almost always
> +both more clear and easier to read the expanded version.

It would be fine with me, but there are a lot of pedants out there,
and I'd rather we avoided bug reports telling us "why don't you do as
you say and remove all the e.g.'s from your own manuals."  I'd like to
avoid the endless disputes such bug reports tend to cause.

So could you make the above even less definitive, either by saying

  "Try to avoid using abbreviations like ... as much as possible."

Maybe even add a footnote saying something like "We do occasionally
use these, but try not to overdo it.".

OK?

bug#40011: Remove unnecessary abbreviations from documentation

[Drew Adams]

> There are many such instances to get right, so maybe we can find a way
> forward which avoids changing all of them.
> 
> How about adding something along the lines of the attached patch, and
> leave it at that?  Would that be acceptable?

(minor nit)

* "like"       -> "such as"
* "more clear" -> "clearer"

bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas]

Drew Adams <drew.adams@oracle.com> writes:

>> There are many such instances to get right, so maybe we can find a way
>> forward which avoids changing all of them.
>> 
>> How about adding something along the lines of the attached patch, and
>> leave it at that?  Would that be acceptable?
>
> (minor nit)
>
> * "like"       -> "such as"
> * "more clear" -> "clearer"

Thanks.  As you might know, English is a second language for me so I
really appreciate this kind of input.

Best regards,
Stefan Kangas

bug#40011: Remove unnecessary abbreviations from documentation

[Drew Adams]

> > (minor nit)
> >
> > * "like"       -> "such as"
> > * "more clear" -> "clearer"
> 
> Thanks.  As you might know, English is a
> second language for me so I really
> appreciate this kind of input.

You're welcome.  And this is very minor.
Colloquially many (most?) people use "like"
when they really mean "such as".

The difference is that "such as" includes
those explicit examples - it says "these
and others (like them)"; whereas "like"
says "things similar to these things".

"Like" doesn't explicitly include those
things; it says to use them to get an idea
of what kind of things might be included.

1. The award was given to people like
George Washington.

2. The award was given to people such as
George Washington.

#1 says that people with characteristics
like GW got the award.  #2 says that GW is
an example of the people who got the award.
In case #2, GW got the award.

---

There's nothing wrong with "more clear".
But "clearer" is usually clearer. ;-)

bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas]

[-- Attachment #1: Type: text/plain, Size: 725 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

> It would be fine with me, but there are a lot of pedants out there,
> and I'd rather we avoided bug reports telling us "why don't you do as
> you say and remove all the e.g.'s from your own manuals."  I'd like to
> avoid the endless disputes such bug reports tend to cause.
>
> So could you make the above even less definitive, either by saying
>
>   "Try to avoid using abbreviations like ... as much as possible."
>
> Maybe even add a footnote saying something like "We do occasionally
> use these, but try not to overdo it.".
>
> OK?

Yes, that makes sense, thanks.  Please see the attached patch with
your suggestions (and Drew's input) incorporated.

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Recommend-to-avoid-unnecessary-abbreviations-in-doc.patch --]
[-- Type: text/x-diff, Size: 1241 bytes --]

From f9ece19a97066e4861f4b58631a588d30aa7999b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Mon, 27 Apr 2020 07:53:10 +0200
Subject: [PATCH] Recommend to avoid unnecessary abbreviations in doc

* doc/lispref/tips.texi (Documentation Tips): Recommend to avoid
unnecessary abbreviations.  (Bug#40011)
---
 doc/lispref/tips.texi | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 3b8da35b6c..5b09b2ccea 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -820,6 +820,14 @@ Documentation Tips
 most cases, the meaning is clear with just ``if''.  Otherwise, try to
 find an alternate phrasing that conveys the meaning.
 
+@item
+Try to avoid using abbreviations such as ``e.g.'' (for ``for
+example''), ``i.e.'' (for ``that is''), ``no.'' (for ``number''),
+``c.f.'' (for ``in contrast to'') and ``w.r.t.'' (for ``with respect
+to'') as much as possible.  It is almost always clearer and easier to
+read the expanded version.@footnote{We do use these occasionally, but
+try not to overdo it.}
+
 @item
 When a command is meaningful only in a certain mode or situation,
 do mention that in the documentation string.  For example,
-- 
2.26.2

bug#40011: Remove unnecessary abbreviations from documentation

[Eli Zaretskii]

> From: Stefan Kangas <stefan@marxist.se>
> Cc: 40011@debbugs.gnu.org,  rms@gnu.org
> Date: Mon, 27 Apr 2020 19:08:21 +0200
> 
> > So could you make the above even less definitive, either by saying
> >
> >   "Try to avoid using abbreviations like ... as much as possible."
> >
> > Maybe even add a footnote saying something like "We do occasionally
> > use these, but try not to overdo it.".
> >
> > OK?
> 
> Yes, that makes sense, thanks.  Please see the attached patch with
> your suggestions (and Drew's input) incorporated.

Thanks, this is fine by me.

bug#40011: Remove unnecessary abbreviations from documentation

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  >   "Try to avoid using abbreviations like ... as much as possible."

  > Maybe even add a footnote saying something like "We do occasionally
  > use these, but try not to overdo it.".

We could even say, "We intend to replace these abbreviations,
but we are not in a desperate hurry."


-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#40011: Remove unnecessary abbreviations from documentation

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > How about adding something along the lines of the attached patch, and
  > leave it at that?  Would that be acceptable?

I agree with it.

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas]

close 40011 27.1
thanks

Eli Zaretskii <eliz@gnu.org> writes:

> Thanks, this is fine by me.

Now pushed to emacs-27 as commit 1d477a0fec.  Closing.

Best regards,
Stefan Kangas