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

[Michael Turner]

Thanks, Loïc. Now I'll start to explicate, showing that there an awful
lot of assumptions about the target audience in your brief summary,
while also getting the thing partly written in the process.

On Thu, Jun 7, 2012 at 6:38 PM, Loïc Hoguin <essen@REDACTED> wrote:
> On 06/07/2012 11:30 AM, Michael Turner wrote:
>>
>> (0) get the necessary batch of files
>
>
> https://github.com/erlang/otp/wiki/Submitting-patches

What this needs to be clear in order to almost anyone hitting that
"How you can help" link:

The documentation for Erlang/OTP is stored on github, a source code
repository, with the Erlang/OTP source. Indeed, some of the
documentation is basically *in* the source code -- special tools are
used to generate much of the reference manual pages from the code.
We'll show you how to find the relevant file, below.

If you don't have a github account already, you'll need one. You'll
also need to learn some basic git commands. These are covered in this
tutorial.

>> (1) locate the right file
>
>
> lib/<application>/doc/src for user guides,
> lib/<application>/src for reference edocs

How do you get from the URL of the documentation you want to fix to a
file name, so that you can edit that file?

In general, if it's what Erlang/OTP calls an "application" (not to be
confused with the more common meaning), you can find it

  lib/<application>/doc/src

if it's a user guide, and

  lib/<application>/src

if it's in a reference manual.

> Or good old: git grep "string you're looking for"

[Note: it's not "good" or "old" for those who don't know git. I'd
expand this a bit more.]

> Or any of the thousand other ways of finding what you're looking for in
> source code.

[Yes, but if you can just tell people the top three easiest ways, you
get about 99% coverage for your audience.]

>> (2) edit it
>
>
> Edit it.

[Yes, but where? It looks like there's a way to do this right at
github, but it also looks like it's either buggy or potentially
confusing. You need to tell them how to get what they want to edit,
for editing, on their own machine, if that's the preferred option.
Yes, believe it: lots of people have never used github.]

>> (3) verify that the page is still generated correctly
>
>
> https://github.com/erlang/otp/wiki/Documentation

[Very likely, this step precedes the others. You also want to help
people out if they aren't interested in figuring out how to get FOP or
other dependencies for PDF generation.]

>> (4) submit a patch
>
>
> https://github.com/erlang/otp/wiki/Submitting-patches

I'd refer to this, but since the tutorial would be presumably be
working through a concrete example of a document fix, I'd substitute
the concrete filenames and operations wherever that document (and
other supporting github documentation) keeps things abstract. As Joe
says in his book, you've got to type the stuff in or you're not really
learning it. So give them what they need to type in, for a concrete
example.

-michael turner