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

[Torvald Riegel <triegel at redhat dot com>]

On Sat, 2013-11-23 at 12:00 -0200, Alexandre Oliva wrote:
> There's a linguistics argument to be made here.
> 
> Someone who's reading the manual is there to learn something; they're
> learning not just definitions, but a language.  After all, cryptic
> function names that are very familiar to us may very well be new to
> them.  There's no reason for us to strive to steer away from new words:
> consumers of the manual will deal with that.  There's more: they
> *expect* to and *want* to deal with that; they're reading the manual
> precisely because they want to learn what those new words mean.

Why aren't we using Klingon names then? ;)

Seriously, I don't want people to have to learn a new language.  That's
not what they are here for (I suppose), as Joseph said.  They want to
get stuff done, and that should be efficient for them.

> Now, the binding of words to meaning, to concepts, is totally arbitrary.
> A word is comfortable, familiar, preferable, just because you know what
> it means.

I don't think people remember stuff without taking context into account.
The anecdote you give below is really just pointing out that somebody
didn't consider that the context might (obviously) be different.

> And it is so as long as it does indeed mean what you expect.
> I recall a foreign acquaintaince who came to a conference in Brazil and
> asked me, quite confused, how come the word ânoâ occurred so often in
> Portuguese text but at points in which it didn't seem to indicate a
> negative sentence.  It's a contraction of the Portuguese words for âinâ
> and âtheâ; nothing to do with the English word ânoâ.  But his
> familiarity with English as his (presumably) second language (he is
> Dutch) just got him confused when he tried to guess the meaning of the
> word in a context he was not familiar with.
> 
> Now what's being proposed here is that we avoid inventing new words that
> would carry the precise meanings we need, and instead resort to existing
> words that don't get even close to bringing to mind this meaning, just
> because the words are familiar and thus easier.

I don't see why "environment" or "static-buffer", for example, would be
harder to associate with the full definition compare to "envromt".  The
context for these names is obvious, so I see "enviroment", I need to do
a mental lookup for the one constraint related to the environment, and I
can remember the full definition.  What's the problem with that?  I will
never remember the sentence involving "read-only" that "envromt" is made
up of (honestly, I know you mentioned in it one of your emails, but I
don't remember).

> I liken that to suggesting the words âWarning!  Water!â for a sign meant
> to alert people to dangerously strong currents in a river.  Yeah, the
> danger has to do with water, but *repurposing* the word water to allude
> to something else, namely âdangerously strong currentsâ, is a
> disservice!  Readers might very well think âok, that's ok, I can swimâ.
> It's obviously superior to spell the problem out in full, but if that
> won't fit in the sign, then what?  Considering that foreign tourists
> amount to most of the visitors of the area, and they are sure to have a
> dictionary handy to look up words they're not familiar with, using a
> term that may be unfamiliar to them but present in the dictionary they
> can look up is much better than repurposing a term they probably already
> know, but meaning something not unrelated, but still significantly
> different from what it normally means.

Well, "fast water" wouldn't be the same, and it would still be simpler
words than "currents", right?  Also, to make a fair comparison, the
equivalent of "warning! water" would be "warning! multi-threaded
execution", which is not what Joseph or I are arguing for. "MT-Unsafe:
environment" would rather be something like "Unsafe water: high speed",
which doesn't sound that prone to misunderstanding to me.

> Now, we know our readers are there to learn new words, and our goal in
> the manual is precisely to teach them the meaning of these new words.

I disagree.  The goal is not to have new language, the goal is to
efficiently communicate a certain semantics with a low probability of
being misunderstood.  That doesn't need to involve a new language
necessarily (depending on how wide your definition of "language" is, of
course).

> Reusing terms for different meanings may seem comfortable because you
> don't have to learn new words, but when you realize it means you're
> overloading words, and this means ambiguity, I don't think that's
> advantageous in the end.  You end up faling to convey the very knowledge
> that people were there to learn.

If the context is clear, and the overloaded term is not ambiguous in the
respective context, then overloading can be just fine.  I think that
both holds in case of the MT-Safety constraints.