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

[Michael Turner]

On Fri, Jun 8, 2012 at 7:08 AM, Richard O'Keefe <ok@REDACTED> wrote:
[snip]
> 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.

Not *as* apparent, no. But I've seen some who aren't native speakers
write things on this list that put some native speakers to shame. And
the history of Erlang development is littered with names of people who
I'm sure are native English speakers. (Admittedly, sometimes Joe
sounds like he's been in Sweden too long.)

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

Be that as it may, this thread is (or has become) about how those who
*do* notice such things might be able to contribute to this aspect of
document quality much more easily.

Not to mention the dearth of hyperlinks in the text, a task where
native English ability is far less important.

[snip]

>> 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*.

No, it's embarrassing to me personally, when I rave at someone about
how wonderful Erlang/OTP is, and bring up a manual page about some
cool package, but there it is, right in front of them, unavoidable:
awkward, broken, poorly punctuated English.

Especially when I've pointed out that one of Erlang's strengths is
that it's a professional, industrial-strength product, not just an
open source project.

"Well, you know: it's a bunch of Scandinavians." Yes, I'll have to try
that excuse next time. Except that I also rave about Joe's book. Not
many Swedes named Joe, I think.

>> [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?

Yes. I read it as "technically competent *as an engineer*", because

(a) she has degrees in computer science (from Stanford and MIT at that
-- facts I recalled about her the instant I read her name), and

(b) what followed was an anecdote that I didn't quite get, because
somebody (you?) wrote "Never let an engineer write the documentation"
and I thought you were agreeing with the point -- you certainly didn't
contradict it immediately.

So at first I read your comment on her work as saying that she'd
suggested changes in the documentation to make things more
documentable from *her* point of view (as an engineer), but that they
were still things that the customers didn't understand.

> "Engineer" in this context means "someone who implemented/maintained
> the specific system being documented".

And to me, "engineer" can ALSO mean "an engineer assigned to do
technical writing", which is what your (?) "Never let an engineer
write the documentation" (now followed with any immediate
contradiction of the claim) primed me to think.

Reading involves perception. Unclear writing can distort perception,
by activating the wrong concepts. It happens in speech too. You are
rarely unclear, so I assumed that the assumption I made about your
sentiment, and my misperception that followed, were both correct.

A nice little lesson in itself about writing, come to think of it.

> 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.

I'd like to suggest a better ideal: an intelligent teacher who never
stops thinking about how to clearly explain things to newbies, no
matter how deep he/she gets into a subject. And who never stops
practicing on the newbies.

This might help explain why some of the better lower-division
undergraduate textbooks are written by professors who win high marks
from their students for effective teaching of the subject. These
professors might be able to solve research-level problems in the same
field with ease, but they stay intrigued with the perennial (and
perhaps for them, more challenging) problem of how to make the field
more intuitive and manageable for those completely new to it.

Such people are admittedly as rare as hen's teeth in the more
quotidian livelihood of tech writing. The Kennitas of that world are
rare enough. (I think she was only sidelined because of some injury --
I'm not sure. I'd kill to make use of her on a project myself, if she
were still available.)

Which takes me back to my agenda: what's the *practical*, *dirt-cheap*
way to *eventually* get better quality docs for Erlang/OTP?

Maybe it's only because wikis are what I know best, but I keep coming
back to wikis.

[snip]
> I am not sure what that sentence is directed at.

I hope you now understand how I misunderstood your understanding of
what I understood to be your ... um .... never mind.

[beautiful story about how a need to clarify things for beginners
resulted in a better design, even a better Prolog standard - snipped.]

I agree. In fact, this should be part of the case for Erlang/OTP to
hire tech writers: that a good one can actually provide valuable
feedback to engineers for whom some (initially) counterintuitive,
user-hostile aspect of a system has become second nature.

As some UI guru once said, "The intuitive is the familiar. Period."
Anybody - and especially any *engineer* - who claims they've got
something that's "intuitive" should always be confronted with: "to
whom?"

> 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.

And their edits can easily be reviewed. If they don't pass muster,
they will quickly be reverted by those who think they are good enough
because they actually *are* good -- who tend to be much more devoted
to the wiki as well (And who tend to slightly underestimate their
abilities, according to the Dunning-Kruger Effect.) If someone
contests a revert, it can go to Talk page discussion. If reasoned
discussion doesn't work with the incompetent, the conflict can be
escalated until it comes to the attention of someone whose judgment no
sensible person would question - especially after that arbitrator
explains the judgment. If the problematic editor persists in the face
of that, you ban them.

Wikis are not anarchy.

Wikis are not "waterfall" development either.

Wikis are an entirely new medium for collective effort on text. The
successful wikis have (or evolve) intelligent governance structures.

People will say a lot of silly things about wikis and their governance
until they gain more direct experience of maintaining them. In that,
wikis are like anything in life.

> 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.

You're prone to sweeping generalizations about wikis based on no
direct personal experience of editing them, from what I can tell.
You're appealing to the Dunning-Kruger Effect

   http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect

as an argument against wikis without realizing that you yourself lack
the competence to make these judgments. In fact, every single
objection you make here is something that every experienced editor of
wikis has long since understood. All of these problems have long since
been addressed with various strategies, subject to various trade-offs.

[Me:]
>> 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?

[Richard:]
> How high *is* the bar?  Have you ever submitted a documentation patch
> and had it rejected?

I've never submitted a documentation patch. But on the code itself,
yes. It was rejected as badly formatted. But then Akira Kitada banged
it into better shape, only to see rejected AGAIN -- by someone who
couldn't figure out how he missed it.

  http://erlang.org/pipermail/erlang-patches/2009-September/000472.html

Not exactly earth-shaking, but Akira found it useful, so I count it
toward my good-deeds-done.

You hate amateurs. I can understand that. But the experts fail sometimes too.

If I submitted a patch to the seq_trace documentation so that it
mentioned that seq_trace implements Lamport clocks, and it got
rejected with "we're still thinking about how to work that fact in,
maybe we'll have something in the next release," I think I'd end up
writing Lamport to say, "Can you *believe* these people?"

But I'm used to being able to fix problems like that in under a
minute, because I edit tech wikis. Call me spoiled. Call me an
amateur, even. But this is one that the pros are getting wrong.

[Good stuff about Zettaiir/Atire and INEX work on autolinking]
> ... But we do have some algorithms
> now that, while not wonderful, are better than nothing.

Good ideas, I'm sure. I'm using Erlang to implement a computational
linguistics framework, so I'm definitely keen on those sorts of
solutions myself. But automating a task to get "better than nothing"
shouldn't be the goal here. This is supposed to be documentation by
professionals, for professionals.

As your experience with Kennita shows, the more properly-primed human
intelligence you apply to documentation, the better. An intelligently
administered wiki can funnel the right kinds of eyes to the right
places, at a price-point that Erlang/OTP can afford.

I happen to hate the price constraint. I'd like to sell them on
getting a proper tech writer myself. How likely is that, though? I
mean, look at your own labors of love: you've submitted a number of
EEPs, with excellent ideas, beautifully written. Ericsson haven't
gotten around to a fraction of them. In a decade, in some cases. When
are they going to split the atom already? Who knows? That's got to be
a lot more important than my nitpicks on the documentation. Yet
there's no movement on it. And what does that tell you about their
resource constraints?

-michael turner