gnustandards-commit
[Top][All Lists]
Advanced

[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



reply via email to

[Prev in Thread] Current Thread [Next in Thread]