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

[Richard O'Keefe]

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.  

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

	Never let an engineer write the documentation.

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.

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