Mercurial > gnulib
changeset 40107:367366e0baa0
autoupdate
author | Karl Berry <karl@freefriends.org> |
---|---|
date | Sat, 19 Jan 2019 08:42:53 -0800 |
parents | a15f73f2ba12 |
children | 2b0255784307 |
files | doc/standards.texi |
diffstat | 1 files changed, 22 insertions(+), 1 deletions(-) [+] |
line wrap: on
line diff
--- a/doc/standards.texi Thu Jan 17 19:40:26 2019 +0100 +++ b/doc/standards.texi Sat Jan 19 08:42:53 2019 -0800 @@ -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 @@ 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