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

[Michael Turner]

On Thu, Jun 7, 2012 at 12:56 PM, Richard O'Keefe <ok@REDACTED> wrote:

> I think you are misreading Joe here.
> What I think he means is that only someone who was around
> and involved when a particular piece of software was
> constructed can answer questions like "why is this here?
> why was it done this way?  why is that not here?  why
> wasn't such and such done this apparently better way?"

OK, so (to bring up the example that's freshest in my mind) we have
depend on, say, Ulf Wiger for our explanation of why seq_trace
implements Lamport clocks, because he "was there" (as he insists)

Really? Even when it seems that he --

(a) was unaware that it implements Lamport clocks,
(b) was apparently ignorant of Lamport clocks before I posted about
the problem that seq_trace doesn't mention (by name) that it's
implementing them
(c) is doubtful that they are useful in seq_trace anyway, or thinks
maybe something better could be done, he's not really sure, and
(d) says his NDA means he can't really fully explain what seq_trace
was originally supposed to do.

I read Lamport's paper when it first came out, decades ago, and I have
worked with seq_trace for a couple of months now, on and off. It seems
that   I'm not only in a better position to tell people that seq_trace
implements Lamport clocks, but also WHY it does, even though I had
nothing whatsoever to do with writing seq_trace. Perhaps Kenneth
Lundin would beg to differ, but he's nowhere to be seen in the current
discussion. If it apparently *should* be up to me (for lack of a
better candidate stepping forward), then why not make it *easier* for
the change to be left to me?

If that's a sad state of affairs, it's nevertheless a reality (in this
case, at least.) Your ironclad rule -- "only those present at the
creation" - would only leave readers more ignorant (in this case, at
least.)

[snip]
> It's the author who knows that the true reason is
[snip]

Wow. That defies what I've learned from experience, from when I
started to write code at age 15, to today: still writing code at age
56. If you show an old piece of code to its author and ask "why?",
about half the time he just can't remember. "Did I write that part of
the system?" is a pretty common answer. Told, "yes, I've verified that
you're the author," the usual answer is, "well, we were writing all
that stuff in a big hurry. Sorry, but it's been a very long time ...."

Official documentation should go to certain depths and its coverage
should have a certain breadth, but an explanation like "The API is
like this because it we were writing all this stuff really fast," is
something I can't remember seeing. If I ever wrote some such phrase in
some official documentation, it was probably because, well, I was in a
hurry!

Wikipedia has a rule: "There are no emergencies on Wikipedia."
(Occasionally there are, but they usually involve edits that could get
the Foundation into legal trouble.) Which is to say, given that all
human social action is constrained by "cheap, good, soon - pick any
two", Wikipedia gets some pretty good work done for very cheap, by not
having any deadlines at all. For articles that nobody is interested
in, that can mean zero progress. But it also means that the good stuff
in a wiki is often the product of careful effort made possible by
leisurely contemplation and discussion of a choice of renderings.

The Talk pages on Wikipedia also provide a repository for what would
otherwise be left to fallible memory.

> It's not that a >>Wiki<< cannot contain the right answer
> once it is known, it's that Wiki >>contributors<< other
> than the author or author's close associates cannot in
> general know what the right answer *is*.

"Cannot in general" might be about as useful here as "You cannot, in
general, divide two numbers", because, after all, 0/0 is meaningless.

I'm trying to be pragmatic: a strategy to improve what's already
there, with a technical-writer/editor budget of zero dollars.

> And if the original author or associate is reachable
> enough to put the answer in a Wiki, they are reachable
> enough to put the answer in a book.

Yeah? Ulf was "reachable" on seq_trace, but he only turned out to be a
colossal waste of time. Kenneth Lundin was reachable, but apparently
couldn't be bothered to comment. I've put questions to the list about
seq_trace more than once. Neither was answered.

I could be fixing typos in articles right now. Adding links right now.
If I don't know the reason for something, I can always try asking. If
I can't get a response, I can always use the tried-and-true Usenet
style of getting an answer: write something that might be wrong, and
tell people I did it.

And if those who were "there at the creation" aren't available, that
doesn't mean that there aren't others who, from more recent
experience, might actually know better than the creators.

>> 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)
>>
> This is pretty much the opposite case.  What we have on that
> page is a bunch of post hoc rationalisations about how a thing happens
> not to be abused, not the original inventor's theory about why it
> was *expected* to work.  (If he had such a theory he should not have
> been surprised when it did!)

You mistake my purpose in pointing it out. Yes, it's amateur
sociologizing, but it was only presented as an existence proof that
people have been answering "why" questions on wikis since their
inception.

>> 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.
>
> Which are not contributed by outsiders.

Incorrect. (Also irrelevant: they nevertheless provide reasons.)

I'm just an editor at Wikipedia (which anybody can be, even
anonymously), not an admin or a bureaucrat. I've made a number of
contributions to Wikipedia policies, including direct edits made
without the usual open discussion because they were pretty obvious
improvements in expressing the policy and its purpose, and thus
uncontested by people who watch those pages like hawks.

It's an open process. You might try learning something about it.

> The sad thing is that the budget for a technical writer isn't
> _that_ high.

If they can't afford it, they can't afford it. It's sad that they
can't budget for it. But that's the reality. I'm just trying to
suggest what might produce progress on existing docs even within that
constraint.

Unfortunately, it seems that you and Joe are prone to sweeping
generalizations about wikis, like "nobody ever fixes things" (you've
got two volunteers already, on this very thread), and "outsiders don't
make policy." (I don't even know what you mean by "outsider" and I
should, if there was any such thing, because I've been editing
Wikipedia articles for about 6 years now.)

>> Richard asks, "What's to be gained by lowering the bar?" Clearly he
>> envisions some hoi polloi stinking up the joint.
>
> There is point in lowering the bar IF
> (a) there are people with superior knowledge who are currently
>    prohibited from entering, OR
> (b) there are people with superior editing skills who are currently
>    prohibited from contributing corrections.
>
> Who _are_ these people?

If you count the current bar as "prohibitive", then, in the case of
seq_trace, ME, for one. I now know a lot about how to use it, and I
know more about the theoretical underpinnings, it seems, than someone
(Ulf) who was there at the creation. Neurons are not a reliable
storage device. "I was there" is really not the gold standard here,
after more than a decade has passed. It's the solid, verifiable stuff
-- code, documentation, open literature publications -- that should
determine content when memory becomes unreliable. And it usually does.

> The main barrier I see is that I cannot find anywhere a document
> that says "How to contribute improvements to the Erlang documentation."

You say "barrier", I say "bar". Is there really any difference?

Yes, a serious omission. Which I would say further raises the bar.

> There _is_ a github page about "Submitting patches", which is really
> quite astonishingly open compared with the way things used to be,
> but very strongly suggests that it is about code, not documenttion.

They keep saying that they welcome documentation *patches,* so I
assumed it was the same process as for code.

> I'm pretty sure I recall seeing messages on this list saying that
> improvements to the documentation were welcome.

Well, now you know how you're supposed to do it. And I think that's a
pretty high bar, for documentation.

>> Nice, but with (for example) MediaWiki's footnote extension,
>
> Please, *not* MediaWiki!  A Masters student here studied MediaWiki
> as his topic.  It's grotesquely complex and (surprise surprise,
> NOT) badly documented and the compatibility of the various
> implementations is, um, unimpressive.

"Various implementations" of MediaWiki? There's only one
implementation of MediaWiki, Richard. (There are tons of wiki
*packages*, with varying markup styles, including some with markup
very similar to MediaWiki's.) Which makes me wonder if you're really
talking about the same thing I am. Assuming we are:

MediaWiki is quite complex for the reason that Erlang/OTP is complex:
it needs to solve a lot of problems that have cropped up over a fairly
long period of time.

MediaWiki, like many systems that "just grew" (e.g., OTP), is
"grotesque" in places.

I don't know why anyone would expect otherwise.

> ... (Rather like Markdown, as
> a matter of fact.  There's original Markdown, there's the variant
> GitHub uses, and there's the variant Erlang uses.  For a
> documentation tool, the documentation of Markdown doesn't even
> reach the "barely competent" level.)

I see. So you'd say that the documentation for all the markup that
went into this MediaWiki-based page

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

will be nonexistent, or patchy where it does exist? To me, it looks
like people who understood the physics behind the topic were somehow
also able to learn the markup for mathematics, graphics, even
animations. Or were able get easily help from those who do know those
things, without much trouble.

Erlang/OTP? "We always welcome documentation patches." Period. That's
their "getting started".

>> 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.
>
> All of which sounds utterly unlike any Wiki I've ever seen, with the
> possible exception of Wikipedia.

So? If that's what you want, then in the policies and guidelines for
an Erlang/OTP documentation wiki, just default to the style guide that
Wikipedia uses, with exceptions only as noted.

> The prospect of having to view heavily fragmented documentation

I don't know what you mean by "heavily fragmented." MediaWiki articles
can be as long and monolithic as people desire. The obvious way to
translate the existing docs to a wiki is just a one-for-one
correspondence of articles.

> full of StupidWikiWords is nightmarish.

That's not MediaWiki, Richard. If I want to wikilink "Richard O'Keefe"
in an article about Prolog people, I just bracket it like this:
"[[Richard O'Keefe]]". For example, the markup for the article about
the computer scientist Richard O'Keefe looks like this:

---
Dr '''Richard A. O'Keefe''' is a [[computer science|computer
scientist]], currently working in Department of Computer Science at
the [[University of Otago]] in [[Dunedin]], [[New Zealand]].

He concentrates on languages for [[logic programming]] and
[[functional programming]] (including [[Prolog programming
language|Prolog]], [[Haskell (programming language)|Haskell]], and
[[Erlang programming language|Erlang]]). O'Keefe published well known
and influential book on [[Prolog programming language|Prolog]]
programming: ''The Craft of Prolog'' (ISBN 0-262-15039-5).
---

The main impediments to reading here are in how wikilinking is made to
articles whose titles don't have the exact phrasing found in the
article linking to them. Those are relatively dense in this article
because Wikipedia is a comprehensive encyclopedia, the potential
namespace is all of human knowledge. In an Erlang-specific wiki, it's
pretty unlikely that you'd need to qualify references to the language
as distinct from the mathematician.

If you still find that style "nightmarish", well, (1) life is full of
tradeoffs, I've found this one quite liveable, and (2) WYSIWYG editors
for MediaWiki wikis are making great strides these days, so help is on
the way.

-michael turner