From d2a3dfe3f62e9a4744393aa06fb7ea8da9a4b806 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 19 Jan 2019 08:42:53 -0800 Subject: [PATCH] autoupdate --- doc/standards.texi | 23 ++++++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/doc/standards.texi b/doc/standards.texi index 86c26bb924..681d627b47 100644 --- a/doc/standards.texi +++ b/doc/standards.texi @@ -3,7 +3,7 @@ @setfilename standards.info @settitle GNU Coding Standards @c This date is automagically updated when you save this file: -@set lastupdate August 3, 2018 +@set lastupdate January 14, 2019 @c %**end of header @dircategory GNU organization @@ -3313,6 +3313,27 @@ topic and reads it straight through. This means covering basic topics 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 -- 2.39.5