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

[Michael Turner]

On Wed, Jun 6, 2012 at 7:36 PM, Joe Armstrong <erlang@REDACTED> wrote:

> 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 see where Richard specifically raised that point, but it's
incorrect in any case. There's no reason a wiki can't answer "why"
questions. Indeed, the very first wiki in existence is "meta" on this
point, asking why wikis work at all (much to the bemusement of Ward
Cunningham, the surprised inventor)

  http://c2.com/cgi/wiki?WhyWikiWorks

And many wikis do explain the reasons for things. For example,
Wikipedia has elaborate, polished internal articles explaining the
"why" of its numerous policies and guidelines.

A wiki is a text repository. It doesn't limit the themes of its prose.
(Except insofar as obscenity-style vandalism is a "theme" -- there are
automatic reverters for such edits.) It would take AI for wiki
software to enforce any such rule anyway, right?

> I don't want to guess why code does what it does - I want the author to tell me.

Well, now you know my frustration upon first encountering Lamport
clocks in seq_trace as snippets of pseudocode, but not called Lamport
clocks. "Why that way?" wasn't satisfactorily answered by the ext, and
I was only lucky that the vague memory of Lamport clocks nagged at me
until I got to the bottom of the question. If the seq_trace
documentation had *merely* said, "seq_trace implements Lamport
clocks," I would have been much further down the road to its reasons
even if I *hadn't* already been familiar with them from decades
before. Why? Because I could search on "Lamport clocks" and find lots
of *other* people (including Lamport himself) explaining the "why."

Now, my frustration is: I don't think anybody at Ericsson is going to
fix this soon, and I'd like to fix it, but I have to build the
frickin' docs from scratch just to add four words. Then submit it as a
patch.

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

I would say that "many eyes" is what actually distinguishes "author"
from "writer" or "journalist." The author has *authority* - to be a
select community's final decider about content almost as much as the
constructor of it. Almost all of the better books I've read have
featured long lists of names in the Acknowledgments, together with an
apology to all those whose names and contributions had become too hazy
for specifics. But only the author is The Author.

Problem is, the author model is expensive. Cheap, soon, good -- pick
any two. An author can build a book faster than any crowd, and it can
be as good as anything out there, not to mention better than a crowd's
collective effort. But that's not cheap. That's your bottleneck.

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

It's impressive, but it doesn't solve the problem: as you yourself
admit, Erlang/OTP has no budget for one author, much less three of
them.

Besides, for the existing Erlang/OTP docs, you don't *need*
authorship. You need editing. For nothing. Well-managed wikis can
excel at that.

> The authors are responsable
> for the text - but many people can comment, and the barrier for entry
> for commenting is very small.

Joe, if you've never done it before, go to a locked-down page

  http://en.wikipedia.org/wiki/Wikipedia:Protection_policy#semi

on Wikipedia, like this one

  http://en.wikipedia.org/wiki/Barack_Obama

and click on the "Talk" link.

  http://en.wikipedia.org/wiki/Talk:Barack_Obama

Then, if you like, add your own comment -- you won't need to ask
anybody's permission.

Richard asks, "What's to be gained by lowering the bar?" Clearly he
envisions some hoi polloi stinking up the joint. So let me be careful
about what I mean by "bar": it's the difficulty of getting started as
a contributor. You can still control who's a contributor, while making
the getting-started part much easier in every other way.

If you sloshed all of the Erlang/OTP docs onto a wiki, then limited
the editor base to 10 people all of whom you'd interviewed by phone
for 10 minutes to get a handle on their Erlang/OTP street-smarts, and
then later verified that they had advanced degrees in computer
science, you WILL have lowered the bar, as far as I'm concerned. The
bar is defined, right now, as the skills and orientation and *personal
time* required to start submitting patches to Erlang/OTP documentation
-- a long, multi-step, hardly-snag-free process. Well, if all someone
wants to do is change "is" to "are" for plural agreement, clearing
*that* bar is a hell of lot to ask, isn't it? No wonder you have typos
that sit there for years on end.

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

Nice, but with (for example) MediaWiki's footnote extension, this can
be done by enclosing a link to a section of the article's Talk page
with <ref>...</ref> tags. Not as smooth, but still very doable.

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

The best of worlds is always gonna cost ya. And that's the bottleneck
in improving existing online Erlang/OTP docs.

A voice is perhaps essential for an authored work. But reference
manuals don't really need much "voice" -- they are encyclopedic. Nor
do tutorials -- voice can even distract in that case. They just need
correct information, couched in correct prose of a relatively uniform
and generic style, within a reasonably well-organized structure.

Keeping the bar for contributing even the most minor of corrections to
Erlang/OTP docs as high as the bar for making major changes serves no
purpose that I can understand. An ongoing source of pain for me: stuff
that should really be hyperlinked in the Erlang/OTP docs. There's not
nearly enough of that kind of thing. A paucity of internal links
wouldn't be so bad if there was a search box -- but there isn't! And
that wouldn't be so bad if I could go back out to Google and get the
right page, as the first link -- but I don't, I often get the old,
out-of-date pages served ranking higher.

A wiki would solve all those problems.

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

It would, I'm sure, but in the meantime, those errors and unlinked
phrases just sit there on erlang.org, crying out for improvement. You
could install a wiki in perhaps a few hours. You could probably write
scripts that translate existing content to wiki markup in a few days.
(I've done that kind of thing myself.) If proper reflection of
contributed changes back into github is important, a bit more effort
would get you something that could reap the edit-deltas out of the
wiki (which stores them as deltas -- nothing is ever lost) and submits
them. I wouldn't be surprised if code for that already exists.

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

You'll still need someone who has the time to go through that existing
stuff and figure out what to act on. I.e., those *authors* Erlang/OTP
presently can't afford.

The Wiki Way is: give readers the right to be an *editor* too.

> The trouble with wiki's is a lot on the stuff on wikis is plain
> *wrong*

Solving that problem is largely a question of

(1) access control, which is a reasonably evolved (if still somewhat
underutilized) aspect of the more mature wiki packages

-- and --

(2) making sure that people who are formally responsible for document
correctness get notifications (and links to the diffs -- also
automated) whenever there are changes in the pages they are
responsible for. These people needn't be on the Ericsson payroll
(though undoubtedly employees should be getting notifications); they
can also be trusted volunteers.

> and nobody
> bothers to correct the mistakes.

Not "nobody". For example, I'm one of those weird people who will
spend 30 seconds to sign up for almost any wiki I see a typo in.

If the Erlang docs were on a wiki, I probably would have done hundreds
of corrections of minor stuff (typos, grammatical errors, needed
links) by now.

> We often see the "stupidity of
> crowds" in action.

When you can decide who's in the crowd, you can control its IQ. So it
only depends on how intelligent *you* are, in making the choices. With
packages like MediaWiki, you can decide. You can even automate a
reasonably intelligent decision, to some extent. Here's fairly simple
piece of code: require an e-mail address in the signup for wiki
editing rights, search the archives of the Erlang questions mailing
list for that e-mail address, and if the time between the aspiring
editor's first contribution (if any) and their most recent one is less
than three months, send a refusal. A few worthy cases might fall
through the cracks, but just mention that you're down there under
those cracks, ready to help, and handle them case-by-case.

[snip]

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

I'd like that, but ... what if the bootstrap to a more-Erlang-authors
world is better quality online documentation attracting more people to
the system in the first place? And what if the bootstrap to better
online documentation is greater interactivity in the Erlang community
in refining what online documentation already exists? And what if
you're closer to the book goals if you do something that could
facility that greater community interactivity sooner, perhaps starting
even next week?

That's not out of the realm of possibilities, with wikis.

-michael turner

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