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

[Joe Armstrong]

On Thu, Jun 7, 2012 at 1:41 PM, Michael Turner
<michael.eugene.turner@REDACTED> wrote:
> I'll admit that what I wrote below is not quite fair. It could take
> longer to make a small change to a wiki, starting from scratch.
> Depending on access control policies, I might even have to wait a day
> for a human being to process my request to become an editor for a
> wiki, if that's how the administrator qualifies people.
>
> I've suggested one heuristic for automated approval that's still a
> reasonable fine - and tunable - filter: require an e-mail address,
> match it against contributions to this mailing list, and only do an
> automatic grant if the time between the first contribution and the
> most recent one is above some threshold. Others are possible.
>
> Some wiki packages allow you to submit one or more changes along with
> an application for editorship. The changes will be approved and made
> to the article after you've been approved as an editor; all your
> changes after that point will be immediate.
>
> At any rate, any wiki and any wiki administrative policy would mean
> less time and less to learn, for people who want to make simple
> changes. Github itself hosts wikis about repositories, and I'm sure at
> least some of them are useful. I hope I'm not preaching to a choir
> here about the virtues of wikis, but from Joe's and Richard's
> responses, I suspect not.

The problem isn't the wiki. It's the entire tool chain. A wiki is just
part of this.
We have 1335 XML files containing "the documentation" currently
the DTDs are too complex. Many XML files don't validate and the tool chain
is difficult to install and run externally.

If we reformat the XML into a wiki we will have another problem - back
propagating
the wiki changes into the XML tree.

/Joe

>
> -michael turner
>
> On Thu, Jun 7, 2012 at 8:20 PM, Michael Turner
> <michael.eugene.turner@REDACTED> wrote:
>> As Ulf's blow-by-blow demonstrates, getting from "I want to add a
>> period to the end of a sentence that doesn't have one" in the
>> Erlang/OTP docs to actually adding that period, starting from scratch,
>> is a tortuous path, with diversions like FOP, the problem of
>> installing Erlang/OTP, building the docs, etc. And that's not even the
>> whole story: you're not actually making a change. You're submitting a
>> patch, and people at Ericsson have to review your "append a period"
>> operation. You might not see it online until the next release.
>>
>> I'm now going to time myself on adding a sentence to an embryonic wiki
>> I started not long ago.
>>
>> Tick, tick, tick ...
>>
>> OK, about 35 seconds -- several of which were spent identifying the
>> URL of the wiki and waiting for it to come up. And here's the change.
>>
>>  http://beam.referata.com/w/index.php?title=Main_Page&diff=10&oldid=9
>>
>> I'll time myself on reverting that change:
>>
>>  http://beam.referata.com/w/index.php?title=Main_Page&diff=11&oldid=10
>>
>> About 10 seconds. Some of which were spent waiting because
>> referata.com can be a little slow.
>>
>> Wikis are, of course, utterly retarded, a completely stupid idea. I
>> don't know why anybody ever thought they could work for any purpose
>> whatsoever, because they could only work when an intelligent and
>> devoted community of users contributes to them, and in the Erlang/OTP
>> community, there's an incredible shortage of ...
>>
>> Um, wait, I think maybe there's something wrong with one of my premises.
>>
>> -michael turner
>>
>> On Thu, Jun 7, 2012 at 7:13 PM, Ulf Wiger <ulf@REDACTED> wrote:
>>>
>>> On 7 Jun 2012, at 10:06, Gustav Simonsson wrote:
>>>
>>>> Today the OTP team have dedicated resources for reviewing patches. This means that
>>>> if you write a documentation patch it's almost guaranteed to be included following a review,
>>>> provided it improves the documentation. The time to review a documentation change is also
>>>> typically much shorter compared to reviews of code changes, and can often be done by
>>>> more team members.
>>>
>>> As Richard pointed out, the wiki page on submitting patches
>>> could be extended with some helpful tips on how to make
>>> documentation patches.
>>>
>>> At the very least, the github wiki should have a link to the OTP
>>> installation guide,
>>>
>>> http://www.erlang.org/doc/installation_guide/INSTALL.html
>>>
>>> which among many other things covers what to do when you
>>> run into problems with FOP. For those just wanting to patch
>>> the docs of a single app, it would of course be better to learn
>>> how to avoid FOP entirely, and perhaps even a sneaky way
>>> not to have to build *all* the docs.
>>>
>>> Here's a practical result:
>>>
>>> Now, the installation manual above says that `make` takes
>>> about 5 minutes on a fast machine. I'm not sure what kind of
>>> machine that is, but as an alternative data point, it takes
>>> 21 minutes on my fairly new MacBook Air with a 1.7 GHz
>>> Core i5, 4GB RAM and an SSD. It saddens me to find out
>>> how 'unfast' it is.
>>>
>>> Running `make doc` with fakefop on the same machine
>>> takes 7 minutes.
>>>
>>> (I had FOP installed before, but uninstalled it since it
>>> drove me nuts).
>>>
>>> Once all this is done, stepping down into e.g. sasl
>>> and running `make docs` there takes less than a second.
>>>
>>> Unfortunately, this is not enough to verify the docs
>>> entirely, since I don't get the frame layout.
>>>
>>> (The wiki says to use `make release_docs`, which
>>> is good advice. The INSTALL guide starts out with
>>> `make doc`, and then enters into a discussion about
>>> targets, which doesn't necessarily help me understand
>>> which one will make the html docs render right in my
>>> browser).
>>>
>>> However, running `make release_docs` afterwards
>>> (45 secs, since docs are already made), produces the
>>> full HTML docs  under $ERL_TOP/release/doc/index.html
>>>
>>> Once at this point, making a change, running
>>> `make release_docs` at the app level, and refreshing
>>> the web page, is very quick.
>>>
>>> BR,
>>> Ulf W
>>>
>>>
>>> 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
> _______________________________________________
> erlang-questions mailing list
> erlang-questions@REDACTED
> http://erlang.org/mailman/listinfo/erlang-questions