GNU bug report logs - #40011
Remove unnecessary abbreviations from documentation

Previous Next

Full log

View this message in rfc822 format

From: Stefan Kangas <stefan <at> marxist.se>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 40011 <at> debbugs.gnu.org, rms <at> gnu.org
Subject: bug#40011: Remove unnecessary abbreviations from documentation
Date: Mon, 27 Apr 2020 19:08:21 +0200

[Message part 1 (text/plain, inline)]

Eli Zaretskii <eliz <at> 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

[0001-Recommend-to-avoid-unnecessary-abbreviations-in-doc.patch (text/x-diff, inline)]

From f9ece19a97066e4861f4b58631a588d30aa7999b Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas <at> 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

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.