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

[Michael Turner]

On Fri, Jun 8, 2012 at 7:36 PM, Ulf Wiger <ulf@REDACTED> wrote:
>
> One of my main demands on any wiki-style documentation
> for OTP would be that it supports baselining, and online
> and offline browsing of older baselines.

http://en.wikipedia.org/wiki/Wikipedia:Database_download

> The current OTP documentation, for all its flaws, is at least
> version-consistent. I can check out and build an old version
> of OTP and the docs will be the version that was set in stable
> revision together with the code.

MediaWiki makes it fairly easy to establish (perhaps with a single
template invocation in the article footer) a way to see every previous
"official release" version of a given article.

Here, for example

  http://en.wikipedia.org/w/index.php?title=Erlang_(programming_language)&oldid=465840644

is the version of the Wikipedia article about Erlang from particular
instant in time. I picked it out of the History page for the article.

  http://en.wikipedia.org/w/index.php?title=Erlang_(programming_language)&action=history

See the links in the tabs of any Wikipedia article, if you've never
poked at them before.

The tab called "edit" is particularly powerful, I find.

> I won't say that it *can't* be done with wikis, but even such
> wikis as the Github wiki, which are based on a strong VCS,
> normally don't make this easy.

"Even"? The Github wiki strikes me as kind of crude, to be honest.
Probably because it's based on a "strong VCS", which isn't necessarily
the the right substrate. (But good enough for Github purposes. I admit
I haven't looked very closely at it yet.)

> In the case of the github wiki, you could clone it like any other
> git repository, label it, and do all sorts of things with it, but
> the only access you have to older versions of the pages online
> is through the diffs in the history, and viewing github-flavored
> Markdown off-line is no fun - or at least requires quite a bit of
> work for rendered viewing. Such a solution will not be much
> of an improvement over the current situation.

"Improvement" is in the eyes of the beholder. To me, just being able
to fix a grammatical error in under a minute, and have the rest of the
world see it shortly after I hit "submit", is a vast improvement over
the status quo.

> If there is a wiki out there that can do this, I'd be thrilled to
> hear about it.

I don't see the value-added in cloning an entire wiki, except in the
standard model of revision flow where everything leads to a release
date. Wikis are: fix and release a single page, right now.

Right now there's a page that makes Erlang/OTP look like it's
plagiarizing Leslie Lamport. I want to fix it and release it right
now.

If you want release dates for the wiki, you can warn people of the
release date, start locking down pages and even whole namespaces, and
letting in only a few emergency edits as required, then declare what a
snapshot made on the release day the "version" of the wiki for a given
*software* release. Right after the release, you can start loosening
up again, not least so that individual wiki articles can reflect fresh
reports of the more important new bugs in the new releases of the
modules they document.

We all want the perfect, zero-cost system, right now.

What you can get in reality: good, cheap, soon - pick any two.

Admittedly, "good" is in the eye of the beholder. My "good" might not
be yours. But beware premature judgments of "bad". I'm hearing a lot
of "wikis are trash", "wikis can't do this," "wikis can't do that."
Not to get all Mitt Romney on you, but wikis are people. Including
people with designated powers and responsibilities.

Wikipedia can be edited by anybody, and tries to cover everything. For
an Erlang/OTP wiki that's totally inappropriate. You might instead
parcel out editing rights only to a few dozen people outside Ericsson,
and limit the range of topics to articles on released software plus
methodology outlines like OTP Design Principles. MediaWiki doesn't
have the most advanced access control system in the world. But it can
do that. So can other wiki packages. The older ones still in use have
been evolving for about 17 years now, since Ward Cunningham put up the
Portland Pattern Repository

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

in 1995, in the first wiki.

So if you say, with very little experience editing and managing wikis,
"they can't do X", there's a very good chance you're wrong.

-michael turner

> On 8 Jun 2012, at 00:08, Richard O'Keefe wrote:
>
>> Remember, the issue is not "disconnect".  The problem is
>> - people selected for programming skill, not writing skill (or even
>>   the ability to notice the grammatical errors and typos that bother
>>   you and me),
>> - who know too much about the system (if they didn't, would they
>>   have the confidence to edit the documentation?) to understand what
>>   most needs to be documented.
>> Wikis do not solve this problem, they exacerbate it.
>
> Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
> http://feuerlabs.com
>
>
>
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions