[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
gnustandards standards.texi
From: |
Mike Gerwitz |
Subject: |
gnustandards standards.texi |
Date: |
Fri, 18 Jan 2019 22:34:37 -0500 (EST) |
CVSROOT: /sources/gnustandards
Module name: gnustandards
Changes by: Mike Gerwitz <mikegerwitz> 19/01/18 22:34:37
Modified files:
. : standards.texi
Log message:
Summary: standards.texi (GNU Manuals): Add audience paragraphs
Requested by rms <address@hidden> (address@hidden).
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnustandards/standards.texi?cvsroot=gnustandards&r1=1.257&r2=1.258
Patches:
Index: standards.texi
===================================================================
RCS file: /sources/gnustandards/gnustandards/standards.texi,v
retrieving revision 1.257
retrieving revision 1.258
diff -u -b -r1.257 -r1.258
--- standards.texi 24 Oct 2018 03:59:50 -0000 1.257
+++ standards.texi 19 Jan 2019 03:34:37 -0000 1.258
@@ -3,7 +3,7 @@
@setfilename standards.info
@settitle GNU Coding Standards
@c This date is automagically updated when you save this file:
address@hidden lastupdate August 3, 2018
address@hidden lastupdate January 14, 2019
@c %**end of header
@dircategory GNU organization
@@ -3313,6 +3313,27 @@
at the beginning, and advanced topics only later. This also means
defining every specialized term when it is first used.
+Remember that the audience for a GNU manual (and other GNU
+documentation) is global, and that it will be used for years, maybe
+decades. This means that the reader could have very different cultural
+reference points. Decades from now, all but old folks will have very
+different cultural reference points; many things that "everyone knows
+about" today may be mostly forgotten.
+
+For this reason, try to avoid writing in a way that crucially depends on
+cultural reference points for understanding, or that refers to them in
+ways that would impede reading for someone that doesn't recognize them.
+
+Likewise, be conservative in your choice of words (aside from technical
+terms), linguistic constructs, and spelling: aim to make them
+intelligeble to readers from ten years ago. In any contest for
+trendiness, GNU writing should not even qualify to enter.
+
+It is ok to refer once in a rare while to spacially or temporally
+localized reference points or facts, if it is directly pertinent or as
+an aside. Changing these few things (which in any case stand out) when
+they no longer make sense will not be a lot of work.
+
Programmers tend to carry over the structure of the program as the
structure for its documentation. But this structure is not
necessarily good for explaining how to use the program; it may be
- gnustandards standards.texi,
Mike Gerwitz <=