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

[Michael Turner]

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