Re: Consensus on MT-, AS- and AC-Safety docs.

["Joseph S. Myers" <joseph at codesourcery dot com>]

On Sat, 23 Nov 2013, Alexandre Oliva wrote:

> There's a linguistics argument to be made here.

I think the linguistics can go just as much the other way - people read 
text in much larger blocks than individual letters or syllables, and so 
code-words that aren't made of normal English words or conventional 
abbreviations in meaningful sequence, properly separated rather than run 
together, seriously disrupt readability and are quite likely to be 
ignored, or treated as spelling errors ("incansist" suggests "the writer 
doesn't know how to spell 'inconsistent'" more than it suggests "this is a 
technical term with a special glibc-local definition").

> Someone who's reading the manual is there to learn something; they're
> learning not just definitions, but a language.  After all, cryptic

They're learning the use of glibc functions, not glibc-specific code words 
which will never be of use for anything other than reading the glibc 
manual.  (If there is a standard computer science term for some particular 
issue, not specific to glibc, of course use that term; that's a case where 
there is more use to a reader learning the meaning of some specialist 
language.)

> *expect* to and *want* to deal with that; they're reading the manual
> precisely because they want to learn what those new words mean.

No, they want to learn how to use glibc functions.  Words that are not 
part of how to use the functions (e.g. constants defined in a header that 
are arguments to a function) are a distraction.

-- 
Joseph S. Myers
joseph@codesourcery.com