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

Thu Jun 7 10:06:06 CEST 2012

On 2012-06-06 12:36, Joe Armstrong wrote:
> 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.

Today the OTP team have dedicated resources for reviewing patches. This 
means that
if you write a documentation patch it's almost guaranteed to be included 
following a review,
provided it improves the documentation. The time to review a 
documentation change is also
typically much shorter compared to reviews of code changes, and can 
often be done by
more team members.

The number of documentation patches from the open-source community has 
been growing,
with a nice amount included in R15B and R15B01. Hopefully we'll see even 
more doc patches
as the Erlang community grows.

Regards,
Gustav Simonsson
Erlang/OTP team

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