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

[Michael Turner]

> Unfortunately this thread has nothing to do with Erlang any more, and at
> times could be misinterpreted as ad-hominem arguments, which I am sure
> was never the intention of those contributors.

It still has to do with a proposal for a process for improving the
Erlang documentation, so it's not "nothing to do with Erlang anymore."

However, it has gotten to the point where I'm expending a great deal
of effort on addressing a certain kind of objections to the proposal:
that an Erlang/OTP wiki, even if it started as a literal copy of the
existing documentation, and restricted access to editing for those
most likely to edit in good faith, will necessarily manifest all of
the pathologies of wikis that "just grew" without very little (except
after-the-fact) access control for contributors who misbehave.

And arguing against position IS a waste of time.

> A patch to enable smoother contributions to the Erlang docs would be
> welcomed by all; given the complexity some direction & guidelines from the
> OTP team might facilitate this.
>
> What functionality is required?

Can this be done with a mere "patch". I don't see how, unless you mean
"patch" figuratively. (I *have* proposed that the documentation have a
conspicuous solicitation for help, with a link to a "getting started
with documentation patches" that supplies *all* of the instruction,
inline, to get from "I want to change this word to a plural" to a
submitted patch, even if the submitted has no github account to start.
Is that what you mean?)

My answer? Given that Erlang/OTP has never, and probably will never,
hire a technical writer?

(1) A wiki that starts as a literal copy of the existing documentation.

(2) The (I believe, small) amount of scripting required to
periodically and selectively reflect changes made to the wiki back
into the existing documentation sources, either day-at-a-time or to
reflect new releases of the software.

(3) Access to adminship/editorship limited to Ericsson Erlang/OTP
employees, plus anyone on this list who applies for membership in the
ranks of Erlang/OTP wiki editorship, subject to the approval of an
appointed Erlang/OTP employee. (Alternatively: the signup scripting
might compare the e-mail address you submit with archives of this
mailing list, and only automatically grant editing rights to those who
have been a contributor for more than a few weeks. Subject to later
revocation by Ericsson.)

That last puts ultimate responsibility in the appropriate place, I
believe. Erlang/OTP is not just an open source project, but also a
corporate product. As I've written before on this thread, I don't
think an Erlang/OTP documentation wiki effort can survive without some
degree of substantive official support. The question is: how much?

The design of (3) above should aim at keeping the amount of employee
*monitoring* of wiki edits to an absolute minimum - perhaps a
five-minute daily review of "Recent changes" would do it, with much
less time if there were in fact no changes that day. I'd expect there
would be appreciable peaks of employee activity on the wiki only
around the times when they'd see peak effort on documentation anyway:
shortly before a new release. Ideally, at that point, employees simply
change a header in each article from "Planned for the X.Y.Z release"
to "Made available [or removed, in the case of finalized deprecations]
in release X.Y.Z" (with appropriate changes elsewhere in the article
as needed), while bumping anything that didn't actually make it into
Rel X.Y.Z into a section, "Planned for the X.Y.Z+1 release." These are
the kinds of edits they'd have to make in *some* eventually-public
document anyway (e.g., release notes, manual pages, etc.)

-michael turner