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

[Joe Armstrong]

On Wed, Jun 6, 2012 at 9:26 AM, Michael Turner
<michael.eugene.turner@REDACTED> 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.

Correct. The Erlang/OTP documentation  has never had a specific budget.
The documentation has to be "good enough for internal use" -
Internally you can "always ask the guy who wrote the code" - it is a
source of never-ending amazement
to me that external users can figure out how do do things *without* asking the
authors. For external use the documentation must be better.

I agree with Richard on this one - a wiki cannot answer "why" questions -
inspecting the code might reveal *how* it works but not *why* it was
written this way.
I don't want to guess why code does what it does - I want the author to tell me.

My person favorite model is "one author - many eyes".

I'm really impressed by the real-world haskell site (see for example
http://book.realworldhaskell.org/read/functional-programming.html)

This is a "three authors many eyes" publication. The authors are responsable
for the text - but many people can comment, and the barrier for entry
for commenting is very small. The comments can be replied to by other
people who read the text
and the discussion takes place exactly where it should (ie "under" the
paragraph).
This way, long discussions about clocks and how they work, can be hidden away
under the paragraphs in the text to which they refer.

In later versions the authors can choose to revise the text in the
light of the comments or ignore them.

When my prag book was published it first came out as PDF version, when
70% was written - overnight I has comments on 500 pages of text - this
was * incredibly* helpful and really improved the quality of the text.
I got immediate feedback at a paragraph level - so was able to
reformulate the text *before* chopping down a load of trees.

This is the best of worlds - the book still has a "voice" a point of
view that I can
agree with or disagree with - but many eyes can review the text and find typos
and point out things that they do not understand or which need further
clarification.

I am currently trying to make a similar system for the Erlang documentation
that is inspired by the real-world haskell web-site - so hopefully
this will improve matters.

Given that we are not going to suddenly employ a host of professional
technical writers to improve the documentation, I hope a user-driven
commenting system with
low barriers for entry will help improve matters. We will see, this is
an experiment after all.

I also wish to target e-books - so I can read all the documentation on
a pad computer.


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

The trouble with wiki's is a lot on the stuff on wikis is plain
*wrong* and nobody
bothers to correct the mistakes. We often see the "stupidity of
crowds" in action.

Hidden in the OTP documentation is the stuff for many books - if
anybody feels like writing a book go ahead. Or write a chapter.

If you write a chapter and send it to the guys who wrote the code
you'll find them
*very* helpfully and they will happily point out erros and
misunderstanding in your
text.

We've got books about Erlang now we need books about OTP internals, debugging,
databases, making scalable systems, ...

Cheers

/Joe

>
> -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.
>>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions