Technically correct or conceptually easier?

[Bruno Félix Rezende Ribeiro]

Hello folks,

I’d like to hear your thoughts on documentation that is (hopefully)
understandable, but technically inaccurate or even false.  The sort of
documentation for which correct interpretation depends on having "common
sense", whatever that means.

The form (describe-variable 'inhibit-read-only) gives:

  inhibit-read-only is a variable defined in ‘C source code’.
  Its value is nil

  Documentation:
  Non-nil means disregard read-only status of buffers or characters.
  If the value is t, disregard ‘buffer-read-only’ and all ‘read-only’
  text properties.  If the value is a list, disregard ‘buffer-read-only’
  and disregard a ‘read-only’ text property if the property value
  is a member of the list.

The first sentence of the documentation says:

  Non-nil means disregard read-only status of buffers or characters.

OK.  And what nil means?  I guess the omission of its meaning implies
its meaning is the exact opposite of the one given to a non-nil value;
and apparently this conjecture can be factually verified by
experimentation.

It seems to me that this kind of omission is common throughout the Lisp
documentation, being perhaps an implicit once-stated convention to avoid
redundancy.  This would be a gap filled by the "if, and only if,"
expression (a.k.a. iff or logical equivalence).  Yet the Lisp reference
manual suggests:

   • Avoid using “iff” (a mathematics term meaning “if and only if”),
     since many people are unfamiliar with it and mistake it for a typo.
     In most cases, the meaning is clear with just “if”.  Otherwise, try
     to find an alternate phrasing that conveys the meaning.

Fine.  Let that be.  This is not, however, the main problem I see with
the documentation of ‘inhibit-read-only’.  Its last sentence says:

  If the value is a list, disregard ‘buffer-read-only’ and disregard a
  ‘read-only’ text property if the property value is a member of the
  list.

Well, nil is a list.  Therefore, nil has not the opposite meaning of a
non-nil value for that variable --- what I’m sure is not what is meant,
otherwise it would be factually wrong.  If instead it were said:

  If the value is a *cons*, disregard ‘buffer-read-only’ and disregard a
  ‘read-only’ text property if the property value is a member of the
  *cons*.

That would be correct[1].  Nevertheless, I bet many people would find it
strange, specially because they tend to think of conses as ordered
pairs, and lists as something else --- downplaying their relationship as
a simple implementation detail.[2] Some people could argue that the use
of *cons* in that case was just an artificial (dirty) trick to exclude
nil and dodge the burden of explaining better.

This is an instance of the general dilemma I’m trying to convey: is it
better do document things with conceptual rigor and technical
correctness and leave people somewhat astray until they build their
theoretical maturity or to write documentation in a simplistic manner
(little bit off truth) but that tend to make people with yet naive
understanding more secure of its meaning (and therefore more
productive)?[3]

As my background is mathematics, I guess people may see what I’m
inclined to think.  I’m interested, though, on your view of this
subject.  What do you think?


Footnotes: 

[1] For the usual definition of membership, given by the ‘member’
function.  This is worth noting here because people could understand
(inconsistently) that membership for conses is something else entirely:

  (defun member-cons (elt cons)
    (or (equal elt (car cons))
        (equal elt (cdr cons))))

[2] A view that for Lisp I regard not only as inelegant but incorrect as
well.

[3] Albeit not instigating their growth nor expanding their view on the
complexity of the subject for the lack of conceptual puzzles or
surprises.

-- 
Bruno Félix Rezende Ribeiro (oitofelix) [0x28D618AF]
<http://oitofelix.freeshell.org/>

signature.asc
Description: PGP signature