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

[Michael Turner]

OK, how do I get started then?

And how likely is it that, someday soon, every page on the website
will have a link at the top saying, "See an error? Here's how to
help." With those instructions on how to get started?

Occasionally accepting documentation patches whenever offered doesn't
seem to be resulting in cleanup of errors that have been hanging
around in the documentation for years.

-michael turner



On Thu, Jun 7, 2012 at 5:06 PM, Gustav Simonsson <gustav@REDACTED> wrote:
> 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
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions