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

[Ulf Wiger]

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.

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.

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.

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.

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

BR,
Ulf W

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