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

[Michael Turner]

> 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. For example, this very thread branches off from a discussion of
tracing that includes a fight over what I consider an egregious
omission from the seq_trace documentation. And here's one of the
relevant pages about Erlang tracing, from 2007

  http://web.archive.org/web/20071116203524/http://www.erlang.org//doc/apps/et/et_intro.html

Grammatical error: "The following prerequisites is required for
understanding ...."

Here's that same page, now:

  http://www.erlang.org/doc/apps/et/et_intro.html

Same damned error. And, just after the heading "1.1  Scope and
Purpose", there's a new error: a paragraph consisting of a single
apostrophe.

Both versions contain a chilling circularity in the "prerequisites":
"familiarity with the Erlang system and Erlang programming in general
and the especially the art of Erlang tracing."

"Especially the art of Erlang tracing"? But, um, wait: isn't "the art
of Erlang tracing" precisely what I'm aiming to learn, in reading the
"et" documentation for which this passage is the introduction? Or if
not, well, where DO I pick that up?

Given my choice of worlds, Richard, I'd choose what you prefer:
technical writers on salary. And given a choice of technical writers,
I'd choose the bodhisattvas of the field: people with masters degrees
in computer science who have decided that working on clearer
documentation will help lead, in its own small way, to the
enlightenment of all sentient beings.

Given *reality*, I propose a wiki.

-michael

On Wed, Jun 6, 2012 at 7:53 AM, Richard O'Keefe <ok@REDACTED> wrote:
>
> On 6/06/2012, at 3:30 AM, Michael Turner wrote:
>> But really: just give me a wiki. Give everybody a wiki. Write scripts
>> to update the repo from the wiki diffs, if that's so important.
>
> For the sake of suffering humanity, forfend!
>
> The next time someone offers me a wiki instead of documentation,
> I am going to be exceedingly angry.  I have never yet found any
> wikified documentation that was worth printing to wipe my arse with.
>
> I do apologise for the vulgarity, but good documentation needs
> good technical writing and technical writing is a skill that is
> distinct from programming, although some people can do both well.
> It needs a *global* view as well as attention to fine detail.
>
>> Generally, lower the bar for entry, for those who want to improve the
>> documentation, and the documentation *will* improve.
>
> Someone recently wrote something about the sky turning green then
> yellow, didn't they?  How is *lowering the bar* going to result in
> anything *improving*?  It might get more *voluminous*, but better?
>
> What we really need is a small number of good technical writers
> and money to pay them.
>