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

[Richard O'Keefe]

On 7/06/2012, at 1:50 AM, Michael Turner wrote:

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

I read this as
	"I agree with Richard on this one.
	 One reason for this is that a wiki cannot answer ..."

> but it's
> incorrect in any case.

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

For example, looking at some particular piece of Erlang
code, an outsider might entertain three hypotheses:

  (a) the author was ignorant and didn't know about
      funs or list comprehensions
  (b) the author knew about them but didn't like them
  (c) the author knew and liked them but thought they
      were too slow.

It's the author who knows that the true reason is

  (d) the code was written before those features were
      added to the language.

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

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.

Last night my departmental laptop developed some sort of
software fault.  It boots happily into Windows but not
the operating system that came with it.  Only that system
has the password for the broadband modem.  Any Erlang
documentation I read tonight will have to be good old
paper.

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


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

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

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

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

The main barrier I see is that I cannot find anywhere a document
that says "How to contribute improvements to the Erlang documentation."
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.

I'm pretty sure I recall seeing messages on this list saying that
improvements to the documentation were welcome.
>> 
> 
> 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.  (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.)

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

The prospect of having to view heavily fragmented documentation
full of StupidWikiWords is nightmarish.