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

[Michael Turner]

On Thu, Jun 7, 2012 at 10:53 AM, Richard O'Keefe <ok@REDACTED> wrote:
>
> On 6/06/2012, at 7:26 PM, Michael Turner wrote:
>
>>> What we really need is a small number of good technical writers
>>> and money to pay them.
>>
>> Agreed. But guess what? Page after page of Erlang/OTP documentation
>> can be produced as evidence that the team doesn't have the budget for
>> it.
>
> 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.

>>
>> Given *reality*, I propose a wiki.
>
> But that's way too close to the process that gave us the documentation
> we have.  Every time I read any other outfit's Prolog documentation, I
> recall the Quintus Prolog documentation with gladness.  Quintus had
> one policy which led to good documentation, and it is precisely that
> policy you are proposing to throw overboard wearing concrete shoes:

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.

[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.
> (From Stanford, so how could she not be?)  But she wasn't on the
> development team.  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. 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.

> Only *good* technical writers are needed, not *great* ones.
> And one would be a good start.

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?

If you're talking about how to generate *new* documentation, I agree.
In principle. But it's not going to happen.

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.

-michael turner