[erlang-questions] FOP (was: Re: Trace-Driven Development)

[Richard O'Keefe]

On 7/06/2012, at 5:27 PM, Michael Turner wrote:
>> Non sequitur.  It demonstrates that the money _has_ not been spent
>> on good technical writers, not that the money _could_ not have been
>> so spent.
> 
> I'm imagining a reasonable assumption: that glaring typos and
> grammatical errors, at the very least, really do seem like the kind of
> thing they'd fix if they could get the money for it.

Recall that Erlang comes from Sweden.
Things that are "glaring typos and grammatical errors" to a native
speaker of English might very well be not so apparent to a native
speaker of Swedish.  As for people associated with Erlang who might
be native speakers of English, from the messages of one of them I've
gleaned "nieve", "ie", "asked be", "nastyness", number agreement
errors, TAM errors, swapping "you" and "your", "over" for "other",
"of" for "on", "lot's", "starred" for "stared", "the" for "they",
punctuation errors in abundance, in every message there's _something_.

I strongly suspect that many of the people associated with the
development of Erlang don't normally *notice* such things.

I have a colleague here who had part of his education in England at
a time when the Initial Teaching Alphabet was in vogue.  To this day
he is not just bad at spelling but bad at knowing where he's bad at
it.  That's quite consistent with him being an excellent programmer
(if only I could cope with his indentation style I would call him
an exceptional programmer) and a very intelligent innovator in his
field.

> Richard, I'm not aiming for anything near perfection, but rather "not
> embarrassing." It's embarrassing for errors to sit around for years
> while new ones accumulate.

It's embarrassing *if you notice*.

> 
> [To be clear: it's not me writing this next line:]
>>        Never let an engineer write the documentation.
> 
> *Never*? Not even one who's proven his/her worth for years as a
> technical writer? Such people do exist, you know.

>> Our first technical writer, Kennita Watson, was technically competent.

Did you read that sentence?  That means that I *know* that there are
people with programming skills who have proven worth as technical
writers because I worked with one.  (And there were others later.)

"Engineer" in this context means "someone who implemented/maintained
the specific system being documented".  These people know too much.
They have forgotten what it was like *not* knowing.  They are keen
to explain things, but they explain the wrong aspects of those things,
or by reference to other things that they forget people haven't heard
of.

The ideal is someone very like Kennita:  someone with a general technical
background who is *able* to learn the information customers need but does
not know it *yet*, and writes up what she's learned right at the cusp
where she now understands it but vividly remembers not understanding it.

>> On more than one occasion her "how am I expected
>> to document _that_?" resulted in changes to designs we "engineers"
>> were perfectly happy with but that customers would not have been.
> 
> There's no excuse for not knowing your intended audience.

I am not sure what that sentence is directed at.

Let me give you a specific example of what I was talking about.

One aspect of Edinburgh Prolog which David Warren had thought well enough
of from the beginning was its "totally defined semantics".  Things that
might have been exceptions in other languages simply said 'no solution'
and triggered backtracking.  This was the way Edinburgh Prolog had *always*
been.  It had been clearly and explicitly documented for a long time.
The audience Quintus were writing for was "people who already know about
Prolog and now want to use an efficient Prolog on machines other than
DEC-10s, like VAXen, 68ks, /370s, Xerox D-machines, ..."  We were happy
enough that "functor(T, 37, 37)" failed quietly; that was the way it had
always been, that was the way it had always been documented, that was the
way it was explained in the tutorial material, that was the way people
coming from DEC-10 Prolog or C-Prolog _expected_ it to be.

It was Kennita who persuaded us that this wasn't good enough, because
_she_ found it confusing while learning Prolog, and argued that reporting
obvious errors as errors rather than appealing to "the totally defined
semantics" would be better for customers and for our reputation.  This
ultimately led to my development of the error handling system and the
error classification in Quintus Prolog which can still be traced in the
ISO Prolog standard, although they changed the names of the operations.

> But for a
> wiki, the editing is largely done *by* the intended audience, so
> there's at least less chance of disconnect, even if there's more room
> for (technical) error.

Most of the intended audience will never touch any of the wiki pages.
That will be done by a self-selected minority who *think* they are good.

Remember, the issue is not "disconnect".  The problem is
 - people selected for programming skill, not writing skill (or even
   the ability to notice the grammatical errors and typos that bother
   you and me),
 - who know too much about the system (if they didn't, would they
   have the confidence to edit the documentation?) to understand what
   most needs to be documented.
Wikis do not solve this problem, they exacerbate it.

> 
> What the existing docs need right now is editing. There are vast
> swathes of text calling out for minor fixes. Why let those problems
> sit around for yet more years? Why set the bar for improving them so
> high?

How high *is* the bar?  Have you ever submitted a documentation patch
and had it rejected?

> My beef is primarily with what's already out there, and secondarily
> with how it's packaged online - searching is still a pain, the docs
> are still seriously underlinked.

With searching and linking, help is at hand.

There are plenty of free information retrieval systems out there,
like Zettair and Atire (formerly Ant).  It's dead simple to take
a bunch of HTML files and tell one of these systems "index that
lot", and get good searching.  I am actually rather surprised that
the Erlang documentation site has not done this.

As for linking, the INEX consortium has seen a fair bit of research
on automatic linking.  The reference task had been to try to match
the linking in the Wikipedia; that's now understood as having too
many links that are not very useful.  But we do have some algorithms
now that, while not wonderful, are better than nothing.