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

[Tuncer Ayaz]

On Tue, Jun 5, 2012 at 9:52 AM, Ulf Wiger wrote:

> Having patched the docs myself, my own experience is that the
> biggest frustration is dealing with FOP - it runs out of heap and
> throws exceptions everytime I try to build the whole docs. That, and

http://erlang.org/pipermail/erlang-questions/2010-September/053298.html

xsltproc (from libxslt) - which you probably have installed - is
enough to create man pages and HTML docs. Also, FOP - the last time I
used it - made use of Apache Batik and therefore required X11. This
makes it harder to run in a headless (server) environment. FOP is
only required for generating PDF files.
_______________________________________________
erlang-questions mailing list
erlang-q...@erlang.org
http://erlang.org/mailman/listinfo/erlang-questions

[Michael Turner]

Right you are, Tuncer. IIRC, I had to do some surgery on the build
scripts to circumvent FOP, since I was trying to build in a server
environment. I don't remember any obvious command-line option for
getting around it. Maybe things are better now. At the time, it seemed
a needless complication for those of us who have been (and perhaps
still could be) motivated to improve the documentation.

But really: just give me a wiki. Give everybody a wiki. Write scripts
to update the repo from the wiki diffs, if that's so important.
Generally, lower the bar for entry, for those who want to improve the
documentation, and the documentation *will* improve. (Yes, there's
such a thing as too low; I've policed wikis for spam, it can get
tedious. But there are well-known, easily implemented policies that
prevent 99.9% of that kind of thing.)

-michael turner

[Richard O'Keefe]

On 6/06/2012, at 3:30 AM, Michael Turner wrote:
> But really: just give me a wiki. Give everybody a wiki. Write scripts
> to update the repo from the wiki diffs, if that's so important.

For the sake of suffering humanity, forfend!

The next time someone offers me a wiki instead of documentation,
I am going to be exceedingly angry. I have never yet found any
wikified documentation that was worth printing to wipe my arse with.

I do apologise for the vulgarity, but good documentation needs
good technical writing and technical writing is a skill that is
distinct from programming, although some people can do both well.
It needs a *global* view as well as attention to fine detail.

> Generally, lower the bar for entry, for those who want to improve the
> documentation, and the documentation *will* improve.

Someone recently wrote something about the sky turning green then
yellow, didn't they? How is *lowering the bar* going to result in
anything *improving*? It might get more *voluminous*, but better?

What we really need is a small number of good technical writers
and money to pay them.

[Michael Turner]

> What we really need is a small number of good technical writers
> and money to pay them.

Agreed. But guess what? Page after page of Erlang/OTP documentation
can be produced as evidence that the team doesn't have the budget for
it. For example, this very thread branches off from a discussion of
tracing that includes a fight over what I consider an egregious
omission from the seq_trace documentation. And here's one of the
relevant pages about Erlang tracing, from 2007

http://web.archive.org/web/20071116203524/http://www.erlang.org//doc/apps/et/et_intro.html

Grammatical error: "The following prerequisites is required for
understanding ...."

Here's that same page, now:

http://www.erlang.org/doc/apps/et/et_intro.html

Same damned error. And, just after the heading "1.1 Scope and
Purpose", there's a new error: a paragraph consisting of a single
apostrophe.

Both versions contain a chilling circularity in the "prerequisites":
"familiarity with the Erlang system and Erlang programming in general
and the especially the art of Erlang tracing."

"Especially the art of Erlang tracing"? But, um, wait: isn't "the art
of Erlang tracing" precisely what I'm aiming to learn, in reading the
"et" documentation for which this passage is the introduction? Or if
not, well, where DO I pick that up?

Given my choice of worlds, Richard, I'd choose what you prefer:
technical writers on salary. And given a choice of technical writers,
I'd choose the bodhisattvas of the field: people with masters degrees
in computer science who have decided that working on clearer
documentation will help lead, in its own small way, to the
enlightenment of all sentient beings.

Given *reality*, I propose a wiki.

-michael

[Joe Armstrong]

On Wed, Jun 6, 2012 at 9:26 AM, Michael Turner
<michael.eu...@gmail.com> wrote:
>> What we really need is a small number of good technical writers
>> and money to pay them.
>
> Agreed. But guess what? Page after page of Erlang/OTP documentation
> can be produced as evidence that the team doesn't have the budget for
> it.

Correct. The Erlang/OTP documentation has never had a specific budget.
The documentation has to be "good enough for internal use" -
Internally you can "always ask the guy who wrote the code" - it is a
source of never-ending amazement
to me that external users can figure out how do do things *without* asking the
authors. For external use the documentation must be better.

I agree with Richard on this one - a wiki cannot answer "why" questions -
inspecting the code might reveal *how* it works but not *why* it was
written this way.
I don't want to guess why code does what it does - I want the author to tell me.

My person favorite model is "one author - many eyes".

I'm really impressed by the real-world haskell site (see for example
http://book.realworldhaskell.org/read/functional-programming.html)

This is a "three authors many eyes" publication. The authors are responsable
for the text - but many people can comment, and the barrier for entry
for commenting is very small. The comments can be replied to by other
people who read the text
and the discussion takes place exactly where it should (ie "under" the
paragraph).
This way, long discussions about clocks and how they work, can be hidden away
under the paragraphs in the text to which they refer.

In later versions the authors can choose to revise the text in the
light of the comments or ignore them.

When my prag book was published it first came out as PDF version, when
70% was written - overnight I has comments on 500 pages of text - this
was * incredibly* helpful and really improved the quality of the text.
I got immediate feedback at a paragraph level - so was able to
reformulate the text *before* chopping down a load of trees.

This is the best of worlds - the book still has a "voice" a point of
view that I can
agree with or disagree with - but many eyes can review the text and find typos
and point out things that they do not understand or which need further
clarification.

I am currently trying to make a similar system for the Erlang documentation
that is inspired by the real-world haskell web-site - so hopefully
this will improve matters.

Given that we are not going to suddenly employ a host of professional
technical writers to improve the documentation, I hope a user-driven
commenting system with
low barriers for entry will help improve matters. We will see, this is
an experiment after all.

I also wish to target e-books - so I can read all the documentation on
a pad computer.

The trouble with wiki's is a lot on the stuff on wikis is plain
*wrong* and nobody
bothers to correct the mistakes. We often see the "stupidity of
crowds" in action.

Hidden in the OTP documentation is the stuff for many books - if
anybody feels like writing a book go ahead. Or write a chapter.

If you write a chapter and send it to the guys who wrote the code
you'll find them
*very* helpfully and they will happily point out erros and
misunderstanding in your
text.

We've got books about Erlang now we need books about OTP internals, debugging,
databases, making scalable systems, ...

Cheers

/Joe

[Henning Diedrich]

On 6/6/12 12:36 PM, Joe Armstrong wrote:

it is a source of never-ending amazement
to me that external users can figure out how do do things *without* asking the
authors. 

Glad to hear that, I immediately feel less stupid.

On 6/6/12 12:53 AM, Richard O'Keefe wrote:

What we really need is ... money.

While we may be able to all agree on that one, there is one related thing that may come cheap.

As noted before, Erlang docs seem harder to Google than other docs or programming related information.

In my experience, this keeps being a massive productivity loss.

While I don't understand why that is, this should be sth. that without money, only with decent SEO knowledge, could be fixed very easily, for a big effect.

Especially given the fact that the HTML is generated from sufficiently abstract sources.

My suspicion is that it has to do with the frame layout. But it should be possible to compensate for that and better guide the search engines through it.

I have Googled unsuccessfully, repeatedly, even for stuff that I /knew/ I had read in the Erlang docs. But could not find, except by finally remembering which links I followed from what to where to end up at the forgotten place. I even reverted to grepping the downloaded doc htmls, which I can't recall I ever did for other languages.

Unfortunately, it seems the great effort of http://erldocs.com/ did not help this either.

Does anyone with the right skill set have a comment on that? Concretely: why, if we can agree on that, is it so hard to use Google to find stuff one is looking for in the Erlang docs; and what can be done to solve that?)

 worth printing to wipe my arse with.

I do apologise

There is always that key, top right-hand on the keyboard for immediate regrets.

Henning

[Henning Diedrich]

On 6/6/12 12:36 PM, Joe Armstrong wrote:

I'm really impressed by the real-world haskell site (see for example
http://book.realworldhaskell.org/read/functional-programming.html)

Since you already mentioned that you were thinking of UUIDs, maybe the way was to set up a global comment repository and provide JavaScript links and alternatively a browser plugin that can link to /any/ paragraph on any page to let comments appear after any paragraph anywhere. The JS could be for sites to tie in, which intent to participate. They would not have to change anything in their structure as the JS would just inspect the DOM and add the 'n comments' hooks. The browser plugin for all other.

This annotated web could be complemented with the possibility to also store links between any two paragraphs explicitly, beyond the obvious option of writing URLs into the comment proper.

To compensate for multiple copies or dynamic URLs, the text, stripped of tags, could be hashed to arrive at a technical reference.

This would all only work in 70% of cases. Superficial changes would break the hashes. But it could be an easy way to phase such efforts in.

Henning

[Michael Turner]

On Wed, Jun 6, 2012 at 7:36 PM, Joe Armstrong <erl...@gmail.com> wrote:

> I agree with Richard on this one - a wiki cannot answer "why" questions -
> inspecting the code might reveal *how* it works but not *why* it was
> written this way.

I don't see where Richard specifically raised that point, but it's
incorrect in any case. There's no reason a wiki can't answer "why"
questions. Indeed, the very first wiki in existence is "meta" on this
point, asking why wikis work at all (much to the bemusement of Ward
Cunningham, the surprised inventor)

http://c2.com/cgi/wiki?WhyWikiWorks

And many wikis do explain the reasons for things. For example,
Wikipedia has elaborate, polished internal articles explaining the
"why" of its numerous policies and guidelines.

A wiki is a text repository. It doesn't limit the themes of its prose.
(Except insofar as obscenity-style vandalism is a "theme" -- there are
automatic reverters for such edits.) It would take AI for wiki
software to enforce any such rule anyway, right?

> I don't want to guess why code does what it does - I want the author to tell me.

Well, now you know my frustration upon first encountering Lamport
clocks in seq_trace as snippets of pseudocode, but not called Lamport
clocks. "Why that way?" wasn't satisfactorily answered by the ext, and
I was only lucky that the vague memory of Lamport clocks nagged at me
until I got to the bottom of the question. If the seq_trace
documentation had *merely* said, "seq_trace implements Lamport
clocks," I would have been much further down the road to its reasons
even if I *hadn't* already been familiar with them from decades
before. Why? Because I could search on "Lamport clocks" and find lots
of *other* people (including Lamport himself) explaining the "why."

Now, my frustration is: I don't think anybody at Ericsson is going to
fix this soon, and I'd like to fix it, but I have to build the
frickin' docs from scratch just to add four words. Then submit it as a
patch.

> My person favorite model is "one author - many eyes".

I would say that "many eyes" is what actually distinguishes "author"
from "writer" or "journalist." The author has *authority* - to be a
select community's final decider about content almost as much as the
constructor of it. Almost all of the better books I've read have
featured long lists of names in the Acknowledgments, together with an
apology to all those whose names and contributions had become too hazy
for specifics. But only the author is The Author.

Problem is, the author model is expensive. Cheap, soon, good -- pick
any two. An author can build a book faster than any crowd, and it can
be as good as anything out there, not to mention better than a crowd's
collective effort. But that's not cheap. That's your bottleneck.

> I'm really impressed by the real-world haskell site (see for example
> http://book.realworldhaskell.org/read/functional-programming.html)
>
> This is a "three authors many eyes" publication.

It's impressive, but it doesn't solve the problem: as you yourself
admit, Erlang/OTP has no budget for one author, much less three of
them.

Besides, for the existing Erlang/OTP docs, you don't *need*
authorship. You need editing. For nothing. Well-managed wikis can
excel at that.

> The authors are responsable
> for the text - but many people can comment, and the barrier for entry
> for commenting is very small.

Joe, if you've never done it before, go to a locked-down page

http://en.wikipedia.org/wiki/Wikipedia:Protection_policy#semi

on Wikipedia, like this one

http://en.wikipedia.org/wiki/Barack_Obama

and click on the "Talk" link.

http://en.wikipedia.org/wiki/Talk:Barack_Obama

Then, if you like, add your own comment -- you won't need to ask
anybody's permission.

Richard asks, "What's to be gained by lowering the bar?" Clearly he
envisions some hoi polloi stinking up the joint. So let me be careful
about what I mean by "bar": it's the difficulty of getting started as
a contributor. You can still control who's a contributor, while making
the getting-started part much easier in every other way.

If you sloshed all of the Erlang/OTP docs onto a wiki, then limited
the editor base to 10 people all of whom you'd interviewed by phone
for 10 minutes to get a handle on their Erlang/OTP street-smarts, and
then later verified that they had advanced degrees in computer
science, you WILL have lowered the bar, as far as I'm concerned. The
bar is defined, right now, as the skills and orientation and *personal
time* required to start submitting patches to Erlang/OTP documentation
-- a long, multi-step, hardly-snag-free process. Well, if all someone
wants to do is change "is" to "are" for plural agreement, clearing
*that* bar is a hell of lot to ask, isn't it? No wonder you have typos
that sit there for years on end.

> The comments can be replied to by other
> people who read the text
> and the discussion takes place exactly where it should (ie "under" the
> paragraph).
> This way, long discussions about clocks and how they work, can be hidden away
> under the paragraphs in the text to which they refer.

Nice, but with (for example) MediaWiki's footnote extension, this can
be done by enclosing a link to a section of the article's Talk page
with <ref>...</ref> tags. Not as smooth, but still very doable.

> This is the best of worlds - the book still has a "voice" a point of
> view that I can
> agree with or disagree with - but many eyes can review the text and find typos
> and point out things that they do not understand or which need further
> clarification.

The best of worlds is always gonna cost ya. And that's the bottleneck
in improving existing online Erlang/OTP docs.

A voice is perhaps essential for an authored work. But reference
manuals don't really need much "voice" -- they are encyclopedic. Nor
do tutorials -- voice can even distract in that case. They just need
correct information, couched in correct prose of a relatively uniform
and generic style, within a reasonably well-organized structure.

Keeping the bar for contributing even the most minor of corrections to
Erlang/OTP docs as high as the bar for making major changes serves no
purpose that I can understand. An ongoing source of pain for me: stuff
that should really be hyperlinked in the Erlang/OTP docs. There's not
nearly enough of that kind of thing. A paucity of internal links
wouldn't be so bad if there was a search box -- but there isn't! And
that wouldn't be so bad if I could go back out to Google and get the
right page, as the first link -- but I don't, I often get the old,
out-of-date pages served ranking higher.

A wiki would solve all those problems.

> I am currently trying to make a similar system for the Erlang documentation
> that is inspired by the real-world haskell web-site - so hopefully
> this will improve matters.

It would, I'm sure, but in the meantime, those errors and unlinked
phrases just sit there on erlang.org, crying out for improvement. You
could install a wiki in perhaps a few hours. You could probably write
scripts that translate existing content to wiki markup in a few days.
(I've done that kind of thing myself.) If proper reflection of
contributed changes back into github is important, a bit more effort
would get you something that could reap the edit-deltas out of the
wiki (which stores them as deltas -- nothing is ever lost) and submits
them. I wouldn't be surprised if code for that already exists.

> Given that we are not going to suddenly employ a host of professional
> technical writers to improve the documentation, I hope a user-driven
> commenting system with
> low barriers for entry will help improve matters.

You'll still need someone who has the time to go through that existing
stuff and figure out what to act on. I.e., those *authors* Erlang/OTP
presently can't afford.

The Wiki Way is: give readers the right to be an *editor* too.

> The trouble with wiki's is a lot on the stuff on wikis is plain
> *wrong*

Solving that problem is largely a question of

(1) access control, which is a reasonably evolved (if still somewhat
underutilized) aspect of the more mature wiki packages

-- and --

(2) making sure that people who are formally responsible for document
correctness get notifications (and links to the diffs -- also
automated) whenever there are changes in the pages they are
responsible for. These people needn't be on the Ericsson payroll
(though undoubtedly employees should be getting notifications); they
can also be trusted volunteers.

> and nobody
> bothers to correct the mistakes.

Not "nobody". For example, I'm one of those weird people who will
spend 30 seconds to sign up for almost any wiki I see a typo in.

If the Erlang docs were on a wiki, I probably would have done hundreds
of corrections of minor stuff (typos, grammatical errors, needed
links) by now.

> We often see the "stupidity of
> crowds" in action.

When you can decide who's in the crowd, you can control its IQ. So it
only depends on how intelligent *you* are, in making the choices. With
packages like MediaWiki, you can decide. You can even automate a
reasonably intelligent decision, to some extent. Here's fairly simple
piece of code: require an e-mail address in the signup for wiki
editing rights, search the archives of the Erlang questions mailing
list for that e-mail address, and if the time between the aspiring
editor's first contribution (if any) and their most recent one is less
than three months, send a refusal. A few worthy cases might fall
through the cracks, but just mention that you're down there under
those cracks, ready to help, and handle them case-by-case.

[snip]

> We've got books about Erlang now we need books about OTP internals, debugging,
> databases, making scalable systems, ...

I'd like that, but ... what if the bootstrap to a more-Erlang-authors
world is better quality online documentation attracting more people to
the system in the first place? And what if the bootstrap to better
online documentation is greater interactivity in the Erlang community
in refining what online documentation already exists? And what if
you're closer to the book goals if you do something that could
facility that greater community interactivity sooner, perhaps starting
even next week?

That's not out of the realm of possibilities, with wikis.

-michael turner

[OvermindDL1]

On Wed, Jun 6, 2012 at 7:50 AM, Michael Turner
<michael.eu...@gmail.com> wrote:
>> and nobody
>> bothers to correct the mistakes.
>
> Not "nobody". For example, I'm one of those weird people who will
> spend 30 seconds to sign up for almost any wiki I see a typo in.

For what it is worth, I am one as well. Some sort of user-editable
documentation (even something that I could comment on like the Haskell
one) would be nice.

[Richard O'Keefe]

On 6/06/2012, at 7:26 PM, Michael Turner wrote:

>> What we really need is a small number of good technical writers
>> and money to pay them.
>
> Agreed. But guess what? Page after page of Erlang/OTP documentation
> can be produced as evidence that the team doesn't have the budget for
> it.

Non sequitur. It demonstrates that the money _has_ not been spent
on good technical writers, not that the money _could_ not have been
so spent.

>
> Given *reality*, I propose a wiki.

But that's way too close to the process that gave us the documentation
we have. Every time I read any other outfit's Prolog documentation, I
recall the Quintus Prolog documentation with gladness. Quintus had
one policy which led to good documentation, and it is precisely that
policy you are proposing to throw overboard wearing concrete shoes:

Never let an engineer write the documentation.

Our first technical writer, Kennita Watson, was technically competent.
(From Stanford, so how could she not be?) But she wasn't on the
development team. On more than one occasion her "how am I expected
to document _that_?" resulted in changes to designs we "engineers"
were perfectly happy with but that customers would not have been.

Only *good* technical writers are needed, not *great* ones.
And one would be a good start.

[Richard O'Keefe]

On 7/06/2012, at 1:50 AM, Michael Turner wrote:

> On Wed, Jun 6, 2012 at 7:36 PM, Joe Armstrong <erl...@gmail.com> wrote:
>
>> I agree with Richard on this one - a wiki cannot answer "why" questions -
>> inspecting the code might reveal *how* it works but not *why* it was
>> written this way.
>
> I don't see where Richard specifically raised that point,

I read this as
"I agree with Richard on this one.
One reason for this is that a wiki cannot answer ..."

> but it's
> incorrect in any case.

I think you are misreading Joe here.
What I think he means is that only someone who was around
and involved when a particular piece of software was
constructed can answer questions like "why is this here?
why was it done this way? why is that not here? why
wasn't such and such done this apparently better way?"

For example, looking at some particular piece of Erlang
code, an outsider might entertain three hypotheses:

(a) the author was ignorant and didn't know about
funs or list comprehensions
(b) the author knew about them but didn't like them
(c) the author knew and liked them but thought they
were too slow.

It's the author who knows that the true reason is

(d) the code was written before those features were
added to the language.

It's not that a >>Wiki<< cannot contain the right answer
once it is known, it's that Wiki >>contributors<< other
than the author or author's close associates cannot in
general know what the right answer *is*.

And if the original author or associate is reachable
enough to put the answer in a Wiki, they are reachable
enough to put the answer in a book.

Last night my departmental laptop developed some sort of
software fault. It boots happily into Windows but not
the operating system that came with it. Only that system
has the password for the broadband modem. Any Erlang
documentation I read tonight will have to be good old
paper.

> There's no reason a wiki can't answer "why"
> questions. Indeed, the very first wiki in existence is "meta" on this
> point, asking why wikis work at all (much to the bemusement of Ward
> Cunningham, the surprised inventor)
>

This is pretty much the opposite case. What we have on that
page is a bunch of post hoc rationalisations about how a thing happens
not to be abused, not the original inventor's theory about why it
was *expected* to work. (If he had such a theory he should not have
been surprised when it did!)

> http://c2.com/cgi/wiki?WhyWikiWorks
>
> And many wikis do explain the reasons for things. For example,
> Wikipedia has elaborate, polished internal articles explaining the
> "why" of its numerous policies and guidelines.

Which are not contributed by outsiders.

>
>
> It's impressive, but it doesn't solve the problem: as you yourself
> admit, Erlang/OTP has no budget for one author, much less three of
> them.

The sad thing is that the budget for a technical writer isn't
_that_ high.

> Richard asks, "What's to be gained by lowering the bar?" Clearly he
> envisions some hoi polloi stinking up the joint.

There is point in lowering the bar IF
(a) there are people with superior knowledge who are currently
prohibited from entering, OR
(b) there are people with superior editing skills who are currently
prohibited from contributing corrections.

Who _are_ these people?

The main barrier I see is that I cannot find anywhere a document
that says "How to contribute improvements to the Erlang documentation."
There _is_ a github page about "Submitting patches", which is really
quite astonishingly open compared with the way things used to be,
but very strongly suggests that it is about code, not documenttion.

I'm pretty sure I recall seeing messages on this list saying that
improvements to the documentation were welcome.

>>
>
> Nice, but with (for example) MediaWiki's footnote extension,

Please, *not* MediaWiki! A Masters student here studied MediaWiki
as his topic. It's grotesquely complex and (surprise surprise,
NOT) badly documented and the compatibility of the various
implementations is, um, unimpressive. (Rather like Markdown, as
a matter of fact. There's original Markdown, there's the variant
GitHub uses, and there's the variant Erlang uses. For a
documentation tool, the documentation of Markdown doesn't even
reach the "barely competent" level.)

> A voice is perhaps essential for an authored work. But reference
> manuals don't really need much "voice" -- they are encyclopedic. Nor
> do tutorials -- voice can even distract in that case. They just need
> correct information, couched in correct prose of a relatively uniform
> and generic style, within a reasonably well-organized structure.

All of which sounds utterly unlike any Wiki I've ever seen, with the
possible exception of Wikipedia.

The prospect of having to view heavily fragmented documentation
full of StupidWikiWords is nightmarish.

[Michael Turner]

On Thu, Jun 7, 2012 at 10:53 AM, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
>
> On 6/06/2012, at 7:26 PM, Michael Turner wrote:
>
>>> What we really need is a small number of good technical writers
>>> and money to pay them.
>>
>> Agreed. But guess what? Page after page of Erlang/OTP documentation
>> can be produced as evidence that the team doesn't have the budget for
>> it.
>
> Non sequitur.  It demonstrates that the money _has_ not been spent
> on good technical writers, not that the money _could_ not have been
> so spent.

I'm imagining a reasonable assumption: that glaring typos and
grammatical errors, at the very least, really do seem like the kind of
thing they'd fix if they could get the money for it.

>>
>> Given *reality*, I propose a wiki.
>
> But that's way too close to the process that gave us the documentation
> we have.  Every time I read any other outfit's Prolog documentation, I
> recall the Quintus Prolog documentation with gladness.  Quintus had
> one policy which led to good documentation, and it is precisely that
> policy you are proposing to throw overboard wearing concrete shoes:

Richard, I'm not aiming for anything near perfection, but rather "not
embarrassing." It's embarrassing for errors to sit around for years
while new ones accumulate.

[To be clear: it's not me writing this next line:]

>        Never let an engineer write the documentation.

*Never*? Not even one who's proven his/her worth for years as a
technical writer? Such people do exist, you know.

> Our first technical writer, Kennita Watson, was technically competent.
> (From Stanford, so how could she not be?)  But she wasn't on the
> development team.  On more than one occasion her "how am I expected
> to document _that_?" resulted in changes to designs we "engineers"
> were perfectly happy with but that customers would not have been.

There's no excuse for not knowing your intended audience. But for a
wiki, the editing is largely done *by* the intended audience, so
there's at least less chance of disconnect, even if there's more room
for (technical) error.

> Only *good* technical writers are needed, not *great* ones.
> And one would be a good start.

What the existing docs need right now is editing. There are vast
swathes of text calling out for minor fixes. Why let those problems
sit around for yet more years? Why set the bar for improving them so
high?

If you're talking about how to generate *new* documentation, I agree.
In principle. But it's not going to happen.

My beef is primarily with what's already out there, and secondarily
with how it's packaged online - searching is still a pain, the docs
are still seriously underlinked.

-michael turner

[Matti Oinas]

On Wed, Jun 6, 2012 at 2:55 PM, Henning Diedrich <hd2...@eonblast.com> wrote:
>
> As noted before, Erlang docs seem harder to Google than other docs or
> programming related information.
>

> ...

>
> My suspicion is that it has to do with the frame layout. But it should be possible to compensate for that and better guide the search engines through it.
>

Many times the bad search results problem comes from the fact that
search engine fails to navigate through the site correctly.

I don't know if erlang.org site uses sitemaps but if not then adding
sitemap would be probably the easiest way to help google and other
search engines to understand the content and that way improve search
results.

Documentation of sitemaps can be found from http://www.sitemaps.org/

[Bengt Kleberg]

My first job allowed me to work with 2 technical writers. They had spent
3 years learning how to do technical writing. They where much better at
this than the people that had spent 4 years learning engineering.

If this was solely because of the education, or a result of wanting to
do the job so much that they took the time to learn it, I do not know.


bengt

[Michael Turner]

On Thu, Jun 7, 2012 at 12:56 PM, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:

> I think you are misreading Joe here.
> What I think he means is that only someone who was around
> and involved when a particular piece of software was
> constructed can answer questions like "why is this here?
> why was it done this way?  why is that not here?  why
> wasn't such and such done this apparently better way?"

OK, so (to bring up the example that's freshest in my mind) we have
depend on, say, Ulf Wiger for our explanation of why seq_trace
implements Lamport clocks, because he "was there" (as he insists)

Really? Even when it seems that he --

(a) was unaware that it implements Lamport clocks,
(b) was apparently ignorant of Lamport clocks before I posted about
the problem that seq_trace doesn't mention (by name) that it's
implementing them
(c) is doubtful that they are useful in seq_trace anyway, or thinks
maybe something better could be done, he's not really sure, and
(d) says his NDA means he can't really fully explain what seq_trace
was originally supposed to do.

I read Lamport's paper when it first came out, decades ago, and I have
worked with seq_trace for a couple of months now, on and off. It seems
that I'm not only in a better position to tell people that seq_trace
implements Lamport clocks, but also WHY it does, even though I had
nothing whatsoever to do with writing seq_trace. Perhaps Kenneth
Lundin would beg to differ, but he's nowhere to be seen in the current
discussion. If it apparently *should* be up to me (for lack of a
better candidate stepping forward), then why not make it *easier* for
the change to be left to me?

If that's a sad state of affairs, it's nevertheless a reality (in this
case, at least.) Your ironclad rule -- "only those present at the
creation" - would only leave readers more ignorant (in this case, at
least.)

[snip]

> It's the author who knows that the true reason is

[snip]

Wow. That defies what I've learned from experience, from when I
started to write code at age 15, to today: still writing code at age
56. If you show an old piece of code to its author and ask "why?",
about half the time he just can't remember. "Did I write that part of
the system?" is a pretty common answer. Told, "yes, I've verified that
you're the author," the usual answer is, "well, we were writing all
that stuff in a big hurry. Sorry, but it's been a very long time ...."

Official documentation should go to certain depths and its coverage
should have a certain breadth, but an explanation like "The API is
like this because it we were writing all this stuff really fast," is
something I can't remember seeing. If I ever wrote some such phrase in
some official documentation, it was probably because, well, I was in a
hurry!

Wikipedia has a rule: "There are no emergencies on Wikipedia."
(Occasionally there are, but they usually involve edits that could get
the Foundation into legal trouble.) Which is to say, given that all
human social action is constrained by "cheap, good, soon - pick any
two", Wikipedia gets some pretty good work done for very cheap, by not
having any deadlines at all. For articles that nobody is interested
in, that can mean zero progress. But it also means that the good stuff
in a wiki is often the product of careful effort made possible by
leisurely contemplation and discussion of a choice of renderings.

The Talk pages on Wikipedia also provide a repository for what would
otherwise be left to fallible memory.

> It's not that a >>Wiki<< cannot contain the right answer
> once it is known, it's that Wiki >>contributors<< other
> than the author or author's close associates cannot in
> general know what the right answer *is*.

"Cannot in general" might be about as useful here as "You cannot, in
general, divide two numbers", because, after all, 0/0 is meaningless.

I'm trying to be pragmatic: a strategy to improve what's already
there, with a technical-writer/editor budget of zero dollars.

> And if the original author or associate is reachable
> enough to put the answer in a Wiki, they are reachable
> enough to put the answer in a book.

Yeah? Ulf was "reachable" on seq_trace, but he only turned out to be a
colossal waste of time. Kenneth Lundin was reachable, but apparently
couldn't be bothered to comment. I've put questions to the list about
seq_trace more than once. Neither was answered.

I could be fixing typos in articles right now. Adding links right now.
If I don't know the reason for something, I can always try asking. If
I can't get a response, I can always use the tried-and-true Usenet
style of getting an answer: write something that might be wrong, and
tell people I did it.

And if those who were "there at the creation" aren't available, that
doesn't mean that there aren't others who, from more recent
experience, might actually know better than the creators.

>> There's no reason a wiki can't answer "why"
>> questions. Indeed, the very first wiki in existence is "meta" on this
>> point, asking why wikis work at all (much to the bemusement of Ward
>> Cunningham, the surprised inventor)
>>
> This is pretty much the opposite case.  What we have on that
> page is a bunch of post hoc rationalisations about how a thing happens
> not to be abused, not the original inventor's theory about why it
> was *expected* to work.  (If he had such a theory he should not have
> been surprised when it did!)

You mistake my purpose in pointing it out. Yes, it's amateur
sociologizing, but it was only presented as an existence proof that
people have been answering "why" questions on wikis since their
inception.

>> And many wikis do explain the reasons for things. For example,
>> Wikipedia has elaborate, polished internal articles explaining the
>> "why" of its numerous policies and guidelines.
>
> Which are not contributed by outsiders.

Incorrect. (Also irrelevant: they nevertheless provide reasons.)

I'm just an editor at Wikipedia (which anybody can be, even
anonymously), not an admin or a bureaucrat. I've made a number of
contributions to Wikipedia policies, including direct edits made
without the usual open discussion because they were pretty obvious
improvements in expressing the policy and its purpose, and thus
uncontested by people who watch those pages like hawks.

It's an open process. You might try learning something about it.

> The sad thing is that the budget for a technical writer isn't
> _that_ high.

If they can't afford it, they can't afford it. It's sad that they
can't budget for it. But that's the reality. I'm just trying to
suggest what might produce progress on existing docs even within that
constraint.

Unfortunately, it seems that you and Joe are prone to sweeping
generalizations about wikis, like "nobody ever fixes things" (you've
got two volunteers already, on this very thread), and "outsiders don't
make policy." (I don't even know what you mean by "outsider" and I
should, if there was any such thing, because I've been editing
Wikipedia articles for about 6 years now.)

>> Richard asks, "What's to be gained by lowering the bar?" Clearly he
>> envisions some hoi polloi stinking up the joint.
>
> There is point in lowering the bar IF
> (a) there are people with superior knowledge who are currently
>    prohibited from entering, OR
> (b) there are people with superior editing skills who are currently
>    prohibited from contributing corrections.
>
> Who _are_ these people?

If you count the current bar as "prohibitive", then, in the case of
seq_trace, ME, for one. I now know a lot about how to use it, and I
know more about the theoretical underpinnings, it seems, than someone
(Ulf) who was there at the creation. Neurons are not a reliable
storage device. "I was there" is really not the gold standard here,
after more than a decade has passed. It's the solid, verifiable stuff
-- code, documentation, open literature publications -- that should
determine content when memory becomes unreliable. And it usually does.

> The main barrier I see is that I cannot find anywhere a document
> that says "How to contribute improvements to the Erlang documentation."

You say "barrier", I say "bar". Is there really any difference?

Yes, a serious omission. Which I would say further raises the bar.

> There _is_ a github page about "Submitting patches", which is really
> quite astonishingly open compared with the way things used to be,
> but very strongly suggests that it is about code, not documenttion.

They keep saying that they welcome documentation *patches,* so I
assumed it was the same process as for code.

> I'm pretty sure I recall seeing messages on this list saying that
> improvements to the documentation were welcome.

Well, now you know how you're supposed to do it. And I think that's a
pretty high bar, for documentation.

>> Nice, but with (for example) MediaWiki's footnote extension,
>
> Please, *not* MediaWiki!  A Masters student here studied MediaWiki
> as his topic.  It's grotesquely complex and (surprise surprise,
> NOT) badly documented and the compatibility of the various
> implementations is, um, unimpressive.

"Various implementations" of MediaWiki? There's only one
implementation of MediaWiki, Richard. (There are tons of wiki
*packages*, with varying markup styles, including some with markup
very similar to MediaWiki's.) Which makes me wonder if you're really
talking about the same thing I am. Assuming we are:

MediaWiki is quite complex for the reason that Erlang/OTP is complex:
it needs to solve a lot of problems that have cropped up over a fairly
long period of time.

MediaWiki, like many systems that "just grew" (e.g., OTP), is
"grotesque" in places.

I don't know why anyone would expect otherwise.

> ... (Rather like Markdown, as

> a matter of fact.  There's original Markdown, there's the variant
> GitHub uses, and there's the variant Erlang uses.  For a
> documentation tool, the documentation of Markdown doesn't even
> reach the "barely competent" level.)

I see. So you'd say that the documentation for all the markup that
went into this MediaWiki-based page

http://en.wikipedia.org/wiki/Angular_momentum

will be nonexistent, or patchy where it does exist? To me, it looks
like people who understood the physics behind the topic were somehow
also able to learn the markup for mathematics, graphics, even
animations. Or were able get easily help from those who do know those
things, without much trouble.

Erlang/OTP? "We always welcome documentation patches." Period. That's
their "getting started".

>> A voice is perhaps essential for an authored work. But reference
>> manuals don't really need much "voice" -- they are encyclopedic. Nor
>> do tutorials -- voice can even distract in that case. They just need
>> correct information, couched in correct prose of a relatively uniform
>> and generic style, within a reasonably well-organized structure.
>
> All of which sounds utterly unlike any Wiki I've ever seen, with the
> possible exception of Wikipedia.

So? If that's what you want, then in the policies and guidelines for
an Erlang/OTP documentation wiki, just default to the style guide that
Wikipedia uses, with exceptions only as noted.

> The prospect of having to view heavily fragmented documentation

I don't know what you mean by "heavily fragmented." MediaWiki articles
can be as long and monolithic as people desire. The obvious way to
translate the existing docs to a wiki is just a one-for-one
correspondence of articles.

> full of StupidWikiWords is nightmarish.

That's not MediaWiki, Richard. If I want to wikilink "Richard O'Keefe"
in an article about Prolog people, I just bracket it like this:
"[[Richard O'Keefe]]". For example, the markup for the article about
the computer scientist Richard O'Keefe looks like this:

---
Dr '''Richard A. O'Keefe''' is a [[computer science|computer
scientist]], currently working in Department of Computer Science at
the [[University of Otago]] in [[Dunedin]], [[New Zealand]].

He concentrates on languages for [[logic programming]] and
[[functional programming]] (including [[Prolog programming
language|Prolog]], [[Haskell (programming language)|Haskell]], and
[[Erlang programming language|Erlang]]). O'Keefe published well known
and influential book on [[Prolog programming language|Prolog]]
programming: ''The Craft of Prolog'' (ISBN 0-262-15039-5).
---

The main impediments to reading here are in how wikilinking is made to
articles whose titles don't have the exact phrasing found in the
article linking to them. Those are relatively dense in this article
because Wikipedia is a comprehensive encyclopedia, the potential
namespace is all of human knowledge. In an Erlang-specific wiki, it's
pretty unlikely that you'd need to qualify references to the language
as distinct from the mathematician.

If you still find that style "nightmarish", well, (1) life is full of
tradeoffs, I've found this one quite liveable, and (2) WYSIWYG editors
for MediaWiki wikis are making great strides these days, so help is on
the way.

-michael turner

[Tim McNamara]

On 7 June 2012 12:23, OvermindDL1 <overm...@gmail.com> wrote:
> On Wed, Jun 6, 2012 at 7:50 AM, Michael Turner
> <michael.eu...@gmail.com> wrote:
>>> and nobody
>>> bothers to correct the mistakes.
>>
>> Not "nobody". For example, I'm one of those weird people who will
>> spend 30 seconds to sign up for almost any wiki I see a typo in.
>
> For what it is worth, I am one as well.  Some sort of user-editable
> documentation (even something that I could comment on like the Haskell
> one) would be nice.

One very easy to implement solution would be to put the sources of the
document into GitHub and use pull requests. This is especially handy
these days, given that GitHub supports in-browser editing.

Are the sources for the Erlang documentation written in plain text?

[Gustav Simonsson]

On 2012-06-06 12:36, Joe Armstrong wrote:
> On Wed, Jun 6, 2012 at 9:26 AM, Michael Turner
> <michael.eu...@gmail.com> wrote:
>>> What we really need is a small number of good technical writers
>>> and money to pay them.
>> Agreed. But guess what? Page after page of Erlang/OTP documentation
>> can be produced as evidence that the team doesn't have the budget for
>> it.
> Correct. The Erlang/OTP documentation has never had a specific budget.
> The documentation has to be "good enough for internal use" -
> Internally you can "always ask the guy who wrote the code" - it is a
> source of never-ending amazement
> to me that external users can figure out how do do things *without* asking the
> authors. For external use the documentation must be better.

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.

The number of documentation patches from the open-source community has
been growing,
with a nice amount included in R15B and R15B01. Hopefully we'll see even
more doc patches
as the Erlang community grows.

Regards,
Gustav Simonsson
Erlang/OTP team

[Michael Turner]

OK, how do I get started then?

And how likely is it that, someday soon, every page on the website
will have a link at the top saying, "See an error? Here's how to
help." With those instructions on how to get started?

Occasionally accepting documentation patches whenever offered doesn't
seem to be resulting in cleanup of errors that have been hanging
around in the documentation for years.

-michael turner

[Loïc Hoguin]

On 06/07/2012 10:40 AM, Michael Turner wrote:
> And how likely is it that, someday soon, every page on the website
> will have a link at the top saying, "See an error? Here's how to
> help." With those instructions on how to get started?

Why don't you send a patch that does exactly that?

--
Loïc Hoguin
Erlang Cowboy
Nine Nines

[Michael Turner]

On Thu, Jun 7, 2012 at 5:42 PM, Loïc Hoguin <es...@ninenines.eu> wrote:
> On 06/07/2012 10:40 AM, Michael Turner wrote:
>>
>> And how likely is it that, someday soon, every page on the website
>> will have a link at the top saying, "See an error? Here's how to
>> help." With those instructions on how to get started?
>
>
> Why don't you send a patch that does exactly that?

BECAUSE THAT WOULD BE A DOCUMENTATION PATCH, AND I DON'T KNOW WHERE TO
START IN SUBMITTING DOCUMENTATION PATCHES.

If Erlang/OTP *truly* welcomes this kind of thing, why don't they
quickly write it up and post it?

What you suggest would need to be something that generates the header
(and footers?) of every page, so it's actually programming of a kind,
and for a documentation generator I don't know anything about. It
wouldn't surprise me if figuring it out would require two days of
concerted effort on my part, but only 20 minutes of concerted effort
on the part of someone at Ericsson.

Ericsson can't afford tech writers for Erlang/OTP? OK, fine, I can
understand that.

But ... Ericsson can't take 20 minutes to facilitate user input on the
documentation, in order to (partially) *substitute* for a lack of tech
writers? With the resulting solicitation going live the same day, not
in some future Erlang/OTP release?

That, I cannot understand.

-michael turner

[Gustav Simonsson]

On 2012-06-07 10:51, Michael Turner wrote:
> On Thu, Jun 7, 2012 at 5:42 PM, Loïc Hoguin<es...@ninenines.eu> wrote:
>> On 06/07/2012 10:40 AM, Michael Turner wrote:
>>> And how likely is it that, someday soon, every page on the website
>>> will have a link at the top saying, "See an error? Here's how to
>>> help." With those instructions on how to get started?
>>
>> Why don't you send a patch that does exactly that?
> BECAUSE THAT WOULD BE A DOCUMENTATION PATCH, AND I DON'T KNOW WHERE TO
> START IN SUBMITTING DOCUMENTATION PATCHES.
>
> If Erlang/OTP *truly* welcomes this kind of thing, why don't they
> quickly write it up and post it?

https://github.com/erlang/otp/wiki/Submitting-patches

Regards,
Gustav Simonsson
Erlang/OTP team

>

[Loïc Hoguin]

On 06/07/2012 10:51 AM, Michael Turner wrote:
> What you suggest would need to be something that generates the header
> (and footers?) of every page, so it's actually programming of a kind,
> and for a documentation generator I don't know anything about. It
> wouldn't surprise me if figuring it out would require two days of
> concerted effort on my part, but only 20 minutes of concerted effort
> on the part of someone at Ericsson.

That's a lot of assumptions, you don't seem to even have looked yet.
I'll add an assumption to that:

It probably would have taken less time than to complain about it.

We can do so many great things by assuming instead of actually doing
anything.

--
Loïc Hoguin
Erlang Cowboy
Nine Nines

[Anthony Ramine]

Le 7 juin 2012 à 09:46, Tim McNamara <pape...@timmcnamara.co.nz> a écrit :

> On 7 June 2012 12:23, OvermindDL1 <overm...@gmail.com> wrote:
>> On Wed, Jun 6, 2012 at 7:50 AM, Michael Turner
>> <michael.eu...@gmail.com> wrote:
>>>> and nobody
>>>> bothers to correct the mistakes.
>>>
>>> Not "nobody". For example, I'm one of those weird people who will
>>> spend 30 seconds to sign up for almost any wiki I see a typo in.
>>
>> For what it is worth, I am one as well. Some sort of user-editable
>> documentation (even something that I could comment on like the Haskell
>> one) would be nice.
>
> One very easy to implement solution would be to put the sources of the
> document into GitHub and use pull requests. This is especially handy
> these days, given that GitHub supports in-browser editing.

GitHub in browser editing is annoying and does not let you create new branches.

> Are the sources for the Erlang documentation written in plain text?

XML (with undocumented DTD) + edoc

[Ulf Wiger]

On 7 Jun 2012, at 11:05, Anthony Ramine wrote:

>> Are the sources for the Erlang documentation written in plain text?
>
> XML (with undocumented DTD) + edoc

The DTDs *are* documented:

http://www.erlang.org/doc/apps/erl_docgen/users_guide.html

BR,
Ulf W

Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com

[Michael Turner]

On Thu, Jun 7, 2012 at 6:01 PM, Loïc Hoguin <es...@ninenines.eu> wrote:
> On 06/07/2012 10:51 AM, Michael Turner wrote:
>>
>> What you suggest would need to be something that generates the header
>> (and footers?) of every page, so it's actually programming of a kind,
>> and for a documentation generator I don't know anything about. It
>> wouldn't surprise me if figuring it out would require two days of
>> concerted effort on my part, but only 20 minutes of concerted effort
>> on the part of someone at Ericsson.
>
>
> That's a lot of assumptions, you don't seem to even have looked yet. I'll
> add an assumption to that:
>
> It probably would have taken less time than to complain about it.

Well then, YOU go do it in three minutes or however long YOU think it
would take. Decades of experience in software tells me that if
something seems like it should take 20 minutes but requires first
learning how a system works, it'll almost always take days -- if you
can do it at all. Is it such a strange assumption on my part that
there's somebody in Erlang/OTP who *already* knows how their own
documentation system works? In any case, they can do this a lot more
easily than most people, and if they are sincere in their expressed
desire for documentation patches, it would get more help from more
people on the documentation. It's not the MediaWiki "edit" tab, but it
would be something, at least, besides the bland reaction to complaints
about the documentation that "we are happy to receive documentation
patches."

-michael turner

[Magnus Henoch]

----- Original Message -----
> On 7 June 2012 12:23, OvermindDL1 <overm...@gmail.com> wrote:
> > On Wed, Jun 6, 2012 at 7:50 AM, Michael Turner
> > <michael.eu...@gmail.com> wrote:
> >>> and nobody
> >>> bothers to correct the mistakes.
> >>
> >> Not "nobody". For example, I'm one of those weird people who will
> >> spend 30 seconds to sign up for almost any wiki I see a typo in.
> >
> > For what it is worth, I am one as well.  Some sort of user-editable
> > documentation (even something that I could comment on like the
> > Haskell
> > one) would be nice.
>
> One very easy to implement solution would be to put the sources of
> the
> document into GitHub and use pull requests. This is especially handy
> these days, given that GitHub supports in-browser editing.

So I decided to try this out. I went to
https://github.com/erlang/otp/blob/maint/lib/et/doc/src/et_intro.xml ,
clicked "Edit this file", removed the stray apostrophe on line 43,
typed in a commit message, and clicked "Propose file change". I got
a very fancy 500 error page that changes perspective when I move the
mouse; no sign of anything being committed to my otp fork on Github.

Is there a workaround for that?

Regards,
--
Magnus Henoch
Erlang Solutions Ltd
http://www.erlang-solutions.com/

[Michael Turner]

It's great that DTD docs are available, but I think what's needed is
something more like this:

Imagine someone who'd just like to get rid of the mysterious
single-apostrophe paragraph after the second subject heading in the
introduction to et. That's all. It's embarrassing. Or maybe the
even-more-embarrassing plural-agreement error not long after?

What precise steps would this person take to

(0) get the necessary batch of files
(1) locate the right file
(2) edit it
(3) verify that the page is still generated correctly
(4) submit a patch

?

This kind of thing (typos, grammatical errors, text that really should
be linked but is not) is all over the documentation. I'm only too
happy to fix these, if I can get submitting patches down to a habit.
I'm only too happy to write it up, so that others can participate.

-michael turner

[H. Diedrich]

Where you logged in to your github account while doing it?

Henning

Magnus Henoch schrieb:

[H. Diedrich]

As I understand it, corrections go only to your own fork. Then you can make a pull request from it to the original repo.

My guess is that your fork was still being created in the background.

"Octotip: You are editing a file in a project you do not have write access to. We are forking this project for you (if one does not yet exist) to write your proposed changes to. Submitting a change to this file will write it to a new branch in your fork so you can send a pull request."

Henning

Magnus Henoch schrieb:

[Loïc Hoguin]

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

> (1) locate the right file

lib/<application>/doc/src for user guides,
lib/<application>/src for reference edocs

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

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

> (2) edit it

Edit it.

> (3) verify that the page is still generated correctly

https://github.com/erlang/otp/wiki/Documentation

> (4) submit a patch

https://github.com/erlang/otp/wiki/Submitting-patches

--
Loïc Hoguin
Erlang Cowboy
Nine Nines

[Michael Turner]

> typed in a commit message, and clicked "Propose file change".  I got
> a very fancy 500 error page that changes perspective when I move the
> mouse; no sign of anything being committed to my otp fork on Github.

I tried the same, except for the plural-agreement issue on the same
page, under "Prerequisites."

"Repository temporarily unavailable".

No estimated-time-until-update. Well, OK.

-michael turner

[Magnus Henoch]

Yes, I was. The error page doesn't reflect that, and shows a "Login"
link, but clicking that just takes me back to the dashboard.

Magnus

[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 <es...@ninenines.eu> 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

[Michael Turner]

On Thu, Jun 7, 2012 at 6:47 PM, Magnus Henoch
<magnus...@erlang-solutions.com> wrote:
> Yes, I was.  The error page doesn't reflect that, and shows a "Login"
> link, but clicking that just takes me back to the dashboard.

I was also logged in.

More fun: the changes I made in the editor seem to have been lost,
when I return to the editing page.

It would be nice if it actually worked, snag-free, or at least warned
you about when it wouldn't work.

-michael turner

[H. Diedrich]

I think github-online editing worked, quite nicely even.

The process seems tedious but what you get for free is quite nice.

https://github.com/erlang/otp/pull/24

You  click "edit this file", it creates a github fork for you.
When you change and click "save" the changes are saved to your fork.
Then you are automatically put on the screen where you send a pull request.
As for example the link above.

Pretty neat in my view. Absolutely usable so far. A fully documented and repository-based, click-and-point patching process.

Henning

Magnus Henoch schrieb:

[Ulf Wiger]

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

[Anthony Ramine]

Editing directly from GitHub makes you unable to check that you wrote lines too long (under 80 columns).

Also it produces nondescript branch names like "patch-1".

Furthermore, Erlang/OTP explicitely forbid pull requests for contribution.

For all these points, I would say it's not neat at all.

 

--

Anthony Ramine

[Henning Diedrich]

Sorry for hitting a merry tone. I realize this was inappropriate  ;-)

If it's wrong for OTP I think for other purposes it's still pretty neat.

From the flames in this thread, maybe OTP would care to reconsider.

It's easy to look at the actual patch, the diff, at github and heal the history later.

Henning

[Tim McNamara]

The reason that it is "not neat" is your focus is on side issues. The
real issue is how to make the contributing as simple as possible, thus
leading to better documentation. Expecting people to download the
entire source distribution to fix minor grammar mistakes is far less
neat.

Concerns about column widths are really not that significant.

"patch-1" is good enough for a branch name, merely because it
basically implies that it is a minor change that came through the
GitHub web UI. No one else would use such a convention. Branch names
are far less significant than commit messages, which are strongly
promoted within GitHub's interface.

Pull request policies are just policies. If the OTP team would prefer
a patch file, they simply change the file extension of the URL and
they have a patch file.

[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

[Michael Turner]

On Thu, Jun 7, 2012 at 7:18 PM, Anthony Ramine <n.o...@gmail.com> wrote:
> Editing directly from GitHub makes you unable to check that you wrote lines
> too long (under 80 columns).

The Hollerith Limit seems to be honored mainly in the breach these
days, though I still try to observe it.

> Also it produces nondescript branch names like "patch-1".

If you can get them listed with the edit summaries, maybe that's no so bad.

> Furthermore, Erlang/OTP explicitely forbid pull requests for contribution.
>
> For all these points, I would say it's not neat at all.

If they could make it work with fewer problems like these, it might be
the simplest alternative to wiki-style editing, especially since
github manages it for you. The major drawback I see in an Erlang/OTP
documentation wiki is that there *is* significant management overhead,
especially if it's hard to automate a effective access control.

-michael turner

[Anthony Ramine]

Le 7 juin 2012 à 13:17, Tim McNamara a écrit :

> Branch names
> are far less significant than commit messages, which are strongly
> promoted within GitHub's interface.

Again, there is no easy from the GitHub interface to know for sure
that the commit messages are correctly formatted. Branch names may
be insignificant but commit messages aren't.

[Michael Turner]

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.

-michael turner

[Joe Armstrong]

On Thu, Jun 7, 2012 at 1:41 PM, Michael Turner
<michael.eu...@gmail.com> 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

[Jan Burse]

Bengt Kleberg schrieb:
> My first job allowed me to work with 2 technical writers. They had spent
> 3 years learning how to do technical writing. They where much better at
> this than the people that had spent 4 years learning engineering.
>
> If this was solely because of the education, or a result of wanting to
> do the job so much that they took the time to learn it, I do not know.

Down with classical technical writing. Most valuable source
for a programmer are the comments inside the code written
by the original engineers. If these comments were extensively
written, precicely showing preconditions, postconditions,
motivations and pitfalls, then everything that comes after
it is just shelfware.

Bye

[Richard O'Keefe]

On 7/06/2012, at 5:27 PM, Michael Turner wrote:
>> Non sequitur. It demonstrates that the money _has_ not been spent
>> on good technical writers, not that the money _could_ not have been
>> so spent.
>
> I'm imagining a reasonable assumption: that glaring typos and
> grammatical errors, at the very least, really do seem like the kind of
> thing they'd fix if they could get the money for it.

Recall that Erlang comes from Sweden.
Things that are "glaring typos and grammatical errors" to a native
speaker of English might very well be not so apparent to a native
speaker of Swedish. As for people associated with Erlang who might
be native speakers of English, from the messages of one of them I've
gleaned "nieve", "ie", "asked be", "nastyness", number agreement
errors, TAM errors, swapping "you" and "your", "over" for "other",
"of" for "on", "lot's", "starred" for "stared", "the" for "they",
punctuation errors in abundance, in every message there's _something_.

I strongly suspect that many of the people associated with the
development of Erlang don't normally *notice* such things.

I have a colleague here who had part of his education in England at
a time when the Initial Teaching Alphabet was in vogue. To this day
he is not just bad at spelling but bad at knowing where he's bad at
it. That's quite consistent with him being an excellent programmer
(if only I could cope with his indentation style I would call him
an exceptional programmer) and a very intelligent innovator in his
field.

> Richard, I'm not aiming for anything near perfection, but rather "not
> embarrassing." It's embarrassing for errors to sit around for years
> while new ones accumulate.

It's embarrassing *if you notice*.

>
> [To be clear: it's not me writing this next line:]
>> Never let an engineer write the documentation.
>
> *Never*? Not even one who's proven his/her worth for years as a
> technical writer? Such people do exist, you know.

>> Our first technical writer, Kennita Watson, was technically competent.

Did you read that sentence? That means that I *know* that there are
people with programming skills who have proven worth as technical
writers because I worked with one. (And there were others later.)

"Engineer" in this context means "someone who implemented/maintained
the specific system being documented". These people know too much.
They have forgotten what it was like *not* knowing. They are keen
to explain things, but they explain the wrong aspects of those things,
or by reference to other things that they forget people haven't heard
of.

The ideal is someone very like Kennita: someone with a general technical
background who is *able* to learn the information customers need but does
not know it *yet*, and writes up what she's learned right at the cusp
where she now understands it but vividly remembers not understanding it.

>> On more than one occasion her "how am I expected
>> to document _that_?" resulted in changes to designs we "engineers"
>> were perfectly happy with but that customers would not have been.
>
> There's no excuse for not knowing your intended audience.

I am not sure what that sentence is directed at.

Let me give you a specific example of what I was talking about.

One aspect of Edinburgh Prolog which David Warren had thought well enough
of from the beginning was its "totally defined semantics". Things that
might have been exceptions in other languages simply said 'no solution'
and triggered backtracking. This was the way Edinburgh Prolog had *always*
been. It had been clearly and explicitly documented for a long time.
The audience Quintus were writing for was "people who already know about
Prolog and now want to use an efficient Prolog on machines other than
DEC-10s, like VAXen, 68ks, /370s, Xerox D-machines, ..." We were happy
enough that "functor(T, 37, 37)" failed quietly; that was the way it had
always been, that was the way it had always been documented, that was the
way it was explained in the tutorial material, that was the way people
coming from DEC-10 Prolog or C-Prolog _expected_ it to be.

It was Kennita who persuaded us that this wasn't good enough, because
_she_ found it confusing while learning Prolog, and argued that reporting
obvious errors as errors rather than appealing to "the totally defined
semantics" would be better for customers and for our reputation. This
ultimately led to my development of the error handling system and the
error classification in Quintus Prolog which can still be traced in the
ISO Prolog standard, although they changed the names of the operations.

> But for a
> wiki, the editing is largely done *by* the intended audience, so
> there's at least less chance of disconnect, even if there's more room
> for (technical) error.

Most of the intended audience will never touch any of the wiki pages.
That will be done by a self-selected minority who *think* they are good.

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.

>
> What the existing docs need right now is editing. There are vast
> swathes of text calling out for minor fixes. Why let those problems
> sit around for yet more years? Why set the bar for improving them so
> high?

How high *is* the bar? Have you ever submitted a documentation patch
and had it rejected?

> My beef is primarily with what's already out there, and secondarily
> with how it's packaged online - searching is still a pain, the docs
> are still seriously underlinked.

With searching and linking, help is at hand.

There are plenty of free information retrieval systems out there,
like Zettair and Atire (formerly Ant). It's dead simple to take
a bunch of HTML files and tell one of these systems "index that
lot", and get good searching. I am actually rather surprised that
the Erlang documentation site has not done this.

As for linking, the INEX consortium has seen a fair bit of research
on automatic linking. The reference task had been to try to match
the linking in the Wikipedia; that's now understood as having too
many links that are not very useful. But we do have some algorithms
now that, while not wonderful, are better than nothing.

[Richard O'Keefe]

On 7/06/2012, at 8:40 PM, Michael Turner wrote:
> Occasionally accepting documentation patches whenever offered doesn't
> seem to be resulting in cleanup of errors that have been hanging
> around in the documentation for years.

Since the barrier to getting corrections in is in fact low,
it would appear that people aren't *sending* patches for those errors.

When I am able to build the documentation I will start sending patches.

[Richard O'Keefe]

>
> BECAUSE THAT WOULD BE A DOCUMENTATION PATCH, AND I DON'T KNOW WHERE TO
> START IN SUBMITTING DOCUMENTATION PATCHES.

There is a patches mailing list. It's documented.

[Richard O'Keefe]

On 7/06/2012, at 9:15 PM, Ulf Wiger wrote:
> The DTDs *are* documented:
>
> http://www.erlang.org/doc/apps/erl_docgen/users_guide.html

Great! Many thanks!

Could someone please change the graphics example?
Figure 6.1 does NOT show "A Silly Man" but a man
with hyperelastic skin, so he is suffering from
some kind of connective tissue disease, *possibly*
a form of Ehlers-Danlos Syndrome. A similar
condition produces winged cats
(http://www.messybeast.com/winged-cats.htm).

[Richard O'Keefe]

On 7/06/2012, at 10:13 PM, Ulf Wiger wrote:
> 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

Section 3.8 starts with the non-sentence "GS now Tcl/Tk 8.4."
Presumably the word "uses" or "requires" has dropped out here.

>
> which among many other things covers what to do when you
> run into problems with FOP.

We must be looking at different pages somehow.
I clicked on that link, and searched for FOP.
Just two things turned up:

The "Building Documentation" part of section 3.4 says that
FOP is needed and where to get it.

The "Build Issues" part of section 3.6 mentions problems
with Java running out of memory, suggests a way to cope,
and directs you to an Apache web page.

There is *nothing* about any *other* problems with FOP.
In particular, the problem I ran into yesterday and reported
in this mailing list is *not* there.

Let me show once more what I get when I try 'make docs':

fop -fo ../pdf/stdlib-1.18.1.fo -pdf ../pdf/stdlib-1.18.1.pdf
Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/fop/cli/Main
Caused by: java.lang.ClassNotFoundException: org.apache.fop.cli.Main
at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
at java.security.AccessController.doPrivileged(Native Method)
at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
make[3]: *** [../pdf/stdlib-1.18.1.pdf] Error 1

I have now found the cause: a copy-and-paste error in setting
up $FOP_HOME. That fixed, I ran straight into the out-of-memory
error. The default heap space for Java is just 64MiB; if this is
such a well known problem with such an easy fix, why not just
patch the relevant Makefile(s) to set FOP_OPTS suitably?

[Michael Turner]

On Fri, Jun 8, 2012 at 7:08 AM, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:
[snip]

> Recall that Erlang comes from Sweden.
> Things that are "glaring typos and grammatical errors" to a native
> speaker of English might very well be not so apparent to a native
> speaker of Swedish.

Not *as* apparent, no. But I've seen some who aren't native speakers
write things on this list that put some native speakers to shame. And
the history of Erlang development is littered with names of people who
I'm sure are native English speakers. (Admittedly, sometimes Joe
sounds like he's been in Sweden too long.)

> I strongly suspect that many of the people associated with the
> development of Erlang don't normally *notice* such things.

Be that as it may, this thread is (or has become) about how those who
*do* notice such things might be able to contribute to this aspect of
document quality much more easily.

Not to mention the dearth of hyperlinks in the text, a task where
native English ability is far less important.

[snip]

>> Richard, I'm not aiming for anything near perfection, but rather "not
>> embarrassing." It's embarrassing for errors to sit around for years
>> while new ones accumulate.
>
> It's embarrassing *if you notice*.

No, it's embarrassing to me personally, when I rave at someone about
how wonderful Erlang/OTP is, and bring up a manual page about some
cool package, but there it is, right in front of them, unavoidable:
awkward, broken, poorly punctuated English.

Especially when I've pointed out that one of Erlang's strengths is
that it's a professional, industrial-strength product, not just an
open source project.

"Well, you know: it's a bunch of Scandinavians." Yes, I'll have to try
that excuse next time. Except that I also rave about Joe's book. Not
many Swedes named Joe, I think.

>> [To be clear: it's not me writing this next line:]
>>>        Never let an engineer write the documentation.
>>
>> *Never*? Not even one who's proven his/her worth for years as a
>> technical writer? Such people do exist, you know.
>
>>> Our first technical writer, Kennita Watson, was technically competent.
>
> Did you read that sentence?

Yes. I read it as "technically competent *as an engineer*", because

(a) she has degrees in computer science (from Stanford and MIT at that
-- facts I recalled about her the instant I read her name), and

(b) what followed was an anecdote that I didn't quite get, because
somebody (you?) wrote "Never let an engineer write the documentation"
and I thought you were agreeing with the point -- you certainly didn't
contradict it immediately.

So at first I read your comment on her work as saying that she'd
suggested changes in the documentation to make things more
documentable from *her* point of view (as an engineer), but that they
were still things that the customers didn't understand.

> "Engineer" in this context means "someone who implemented/maintained
> the specific system being documented".

And to me, "engineer" can ALSO mean "an engineer assigned to do
technical writing", which is what your (?) "Never let an engineer
write the documentation" (now followed with any immediate
contradiction of the claim) primed me to think.

Reading involves perception. Unclear writing can distort perception,
by activating the wrong concepts. It happens in speech too. You are
rarely unclear, so I assumed that the assumption I made about your
sentiment, and my misperception that followed, were both correct.

A nice little lesson in itself about writing, come to think of it.

> The ideal is someone very like Kennita:  someone with a general technical
> background who is *able* to learn the information customers need but does
> not know it *yet*, and writes up what she's learned right at the cusp
> where she now understands it but vividly remembers not understanding it.

I'd like to suggest a better ideal: an intelligent teacher who never
stops thinking about how to clearly explain things to newbies, no
matter how deep he/she gets into a subject. And who never stops
practicing on the newbies.

This might help explain why some of the better lower-division
undergraduate textbooks are written by professors who win high marks
from their students for effective teaching of the subject. These
professors might be able to solve research-level problems in the same
field with ease, but they stay intrigued with the perennial (and
perhaps for them, more challenging) problem of how to make the field
more intuitive and manageable for those completely new to it.

Such people are admittedly as rare as hen's teeth in the more
quotidian livelihood of tech writing. The Kennitas of that world are
rare enough. (I think she was only sidelined because of some injury --
I'm not sure. I'd kill to make use of her on a project myself, if she
were still available.)

Which takes me back to my agenda: what's the *practical*, *dirt-cheap*
way to *eventually* get better quality docs for Erlang/OTP?

Maybe it's only because wikis are what I know best, but I keep coming
back to wikis.

[snip]

> I am not sure what that sentence is directed at.

I hope you now understand how I misunderstood your understanding of
what I understood to be your ... um .... never mind.

[beautiful story about how a need to clarify things for beginners
resulted in a better design, even a better Prolog standard - snipped.]

I agree. In fact, this should be part of the case for Erlang/OTP to
hire tech writers: that a good one can actually provide valuable
feedback to engineers for whom some (initially) counterintuitive,
user-hostile aspect of a system has become second nature.

As some UI guru once said, "The intuitive is the familiar. Period."
Anybody - and especially any *engineer* - who claims they've got
something that's "intuitive" should always be confronted with: "to
whom?"

> Most of the intended audience will never touch any of the wiki pages.
> That will be done by a self-selected minority who *think* they are good.

And their edits can easily be reviewed. If they don't pass muster,
they will quickly be reverted by those who think they are good enough
because they actually *are* good -- who tend to be much more devoted
to the wiki as well (And who tend to slightly underestimate their
abilities, according to the Dunning-Kruger Effect.) If someone
contests a revert, it can go to Talk page discussion. If reasoned
discussion doesn't work with the incompetent, the conflict can be
escalated until it comes to the attention of someone whose judgment no
sensible person would question - especially after that arbitrator
explains the judgment. If the problematic editor persists in the face
of that, you ban them.

Wikis are not anarchy.

Wikis are not "waterfall" development either.

Wikis are an entirely new medium for collective effort on text. The
successful wikis have (or evolve) intelligent governance structures.

People will say a lot of silly things about wikis and their governance
until they gain more direct experience of maintaining them. In that,
wikis are like anything in life.

> 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.

You're prone to sweeping generalizations about wikis based on no
direct personal experience of editing them, from what I can tell.
You're appealing to the Dunning-Kruger Effect

http://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect

as an argument against wikis without realizing that you yourself lack
the competence to make these judgments. In fact, every single
objection you make here is something that every experienced editor of
wikis has long since understood. All of these problems have long since
been addressed with various strategies, subject to various trade-offs.

[Me:]

>> What the existing docs need right now is editing. There are vast
>> swathes of text calling out for minor fixes. Why let those problems
>> sit around for yet more years? Why set the bar for improving them so
>> high?

[Richard:]

> How high *is* the bar?  Have you ever submitted a documentation patch
> and had it rejected?

I've never submitted a documentation patch. But on the code itself,
yes. It was rejected as badly formatted. But then Akira Kitada banged
it into better shape, only to see rejected AGAIN -- by someone who
couldn't figure out how he missed it.

http://erlang.org/pipermail/erlang-patches/2009-September/000472.html

Not exactly earth-shaking, but Akira found it useful, so I count it
toward my good-deeds-done.

You hate amateurs. I can understand that. But the experts fail sometimes too.

If I submitted a patch to the seq_trace documentation so that it
mentioned that seq_trace implements Lamport clocks, and it got
rejected with "we're still thinking about how to work that fact in,
maybe we'll have something in the next release," I think I'd end up
writing Lamport to say, "Can you *believe* these people?"

But I'm used to being able to fix problems like that in under a
minute, because I edit tech wikis. Call me spoiled. Call me an
amateur, even. But this is one that the pros are getting wrong.

[Good stuff about Zettaiir/Atire and INEX work on autolinking]
> ... But we do have some algorithms

> now that, while not wonderful, are better than nothing.

Good ideas, I'm sure. I'm using Erlang to implement a computational
linguistics framework, so I'm definitely keen on those sorts of
solutions myself. But automating a task to get "better than nothing"
shouldn't be the goal here. This is supposed to be documentation by
professionals, for professionals.

As your experience with Kennita shows, the more properly-primed human
intelligence you apply to documentation, the better. An intelligently
administered wiki can funnel the right kinds of eyes to the right
places, at a price-point that Erlang/OTP can afford.

I happen to hate the price constraint. I'd like to sell them on
getting a proper tech writer myself. How likely is that, though? I
mean, look at your own labors of love: you've submitted a number of
EEPs, with excellent ideas, beautifully written. Ericsson haven't
gotten around to a fraction of them. In a decade, in some cases. When
are they going to split the atom already? Who knows? That's got to be
a lot more important than my nitpicks on the documentation. Yet
there's no movement on it. And what does that tell you about their
resource constraints?

-michael turner

[Ulf Wiger]

On 8 Jun 2012, at 01:33, Richard O'Keefe wrote:

> We must be looking at different pages somehow.
> I clicked on that link, and searched for FOP.

[…]

> The "Build Issues" part of section 3.6 mentions problems
> with Java running out of memory, suggests a way to cope,
> and directs you to an Apache web page.

Yes, that was what I meant. Apologies for my terseness.
I should perhaps have written something along the lines of
"that page does explain some of the tricky aspects of the OTP
build system, including some of the problems *I* have
encountered. such as the out-of-heap memory problems
with FOP.

Due to time pressures, that was somehow reduced to
"at the very least, the github wiki should have a link…".
I still think it should, but more is definitely needed.

> There is *nothing* about any *other* problems with FOP.
> In particular, the problem I ran into yesterday and reported
> in this mailing list is *not* there.

I can imagine that many people who run into problems don't
think to go to that page, and so are less likely to give any
feedback on it.

> fop -fo ../pdf/stdlib-1.18.1.fo -pdf ../pdf/stdlib-1.18.1.pdf
> Exception in thread "main" java.lang.NoClassDefFoundError: org/apache/fop/cli/Main
> Caused by: java.lang.ClassNotFoundException: org.apache.fop.cli.Main
> at java.net.URLClassLoader$1.run(URLClassLoader.java:202)
> at java.security.AccessController.doPrivileged(Native Method)
> at java.net.URLClassLoader.findClass(URLClassLoader.java:190)
> at java.lang.ClassLoader.loadClass(ClassLoader.java:306)
> at sun.misc.Launcher$AppClassLoader.loadClass(Launcher.java:301)
> at java.lang.ClassLoader.loadClass(ClassLoader.java:247)
> make[3]: *** [../pdf/stdlib-1.18.1.pdf] Error 1
>
> I have now found the cause: a copy-and-paste error in setting
> up $FOP_HOME.

I think the wiki and Erlang docs should clearly discourage people
from running FOP - and 'fakefop' should be the default - *unless*
you want to produce PDFs.

BR,
Ulf W

Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com

[Jan Burse]

Michael Turner schrieb:

> Which takes me back to my agenda: what's the*practical*,*dirt-cheap*

> way to*eventually* get better quality docs for Erlang/OTP?

Since years there are spelling checkers and grammar checkers
around, even on unix command level. Run your docs through it
and you can turn a swenglish text into an english text.

http://www.linfo.org/spell.html

http://www.gnu.org/software/diction/

[Ulf Wiger]

On 8 Jun 2012, at 09:19, Michael Turner wrote:

> If I submitted a patch to the seq_trace documentation so that it
> mentioned that seq_trace implements Lamport clocks, and it got
> rejected with "we're still thinking about how to work that fact in,
> maybe we'll have something in the next release," I think I'd end up
> writing Lamport to say, "Can you *believe* these people?"

Up to this point, I thought you were on a roll with clear,
insightful and respectful discussion not least about the
problems of understanding each other in writing, and
conveying ideas through documentation.

I can understand that certain points can get lost in a long
and heated thread, so let me clarify a few things:

- I don't work for Ericsson (as also apparent from my sig)

- I don't vet patches on OTP. I have to submit patches like
everyone else; sometimes they are rejected, mostly not.

- Whatever changes *I* would like to see to seq_trace, are
my own ideas; It's been quite a while since the topic of
seq_trace came up in any discussions I've had with OTP,
and then only in passing (although I *did* push for changes
to TTB a while back that would make sequence tracing,
and other things, easier, and was glad to finally see the
changes, most of which not made by me, accepted).

In this particular case, the most relevant passage of our
long discussion should be Gustav Simonsson (who *does*
represent OTP) saying that your patch was welcome:

[Gustav:]
> +1
>
> Especially under the "Advanced examples" section there
> is less need for brevity since users clicking on that section
> likely are prepared for multiple, possibly long, examples
> of using the Event Tracer.


Most doc- and other patches are unsolicited. I have a number
of times asked for advance feedback on the list, to get some
indication of whether it would be worth my while to put in the
time and effort to make a patch (in those cases, changes that
affect the API and documentation). Usually, such queries
have gone unanswered, and I'm left to decide for myself
whether I should embark on a project of writing code, test
suites and documentation and making an argument that
(1) the change is an improvement, (2) doesn't break
anything, (3) doesn't confuse users who don't need the
new feature, etc. *That* can easily amount to a week's
worth of work, with no guarantee that it will be accepted.

In the most recent case, it was much, much more than that:
a fairly large addition to mnesia that has been many years
in the making, and was brought to patchworthy status only
through the sponsorship of Klarna, and the help of Roland
Karlsson at Erlang Solutions, since I was no longer in a
position to complete it. That change was actually rejected
a few times in the early stages. For the larger project, we
visited the OTP team to present our ideas and get an
early indication that it was a plausible approach - no
guarantees that it would finally be accepted, but as much
encouragement as was reasonable at the time.
http://www.erlang-factory.com/upload/presentations/601/EUC2012-009.pdf

Personally, I think that's ok. It's my idea, and others may not
agree, or otherwise find it important. However, for everyone
(not least on the OTP team) who spots such requests for
early feedback: it really means a lot to get comments early
on.

As for feedback from me, I'm just another user on the list. I
have never been in a position to decide what goes into OTP
(well, except for being on the EEP committee). Kenneth
has no problem rejecting my advice, although I believe he
values it. The only concrete comments you've gotten this
time from OTP have been words of encouragement: submit
a patch, and it will be accepted as long as it improves the
documentation - not a single hint that they are planning
anything else for seq_trace. We have no reason to think
that they are, but now would of course be a good time
to say so then. :)

I reserve the right to give feedback with the intent of being
helpful, but it is *not* to be interpreted as an opinion from
the Erlang maintainers. Any such opinion must come
straight from the OTP team, preferrably framed in such
a way that it is clear that they are not just engaging in
free and open debate.

There are others who are actually on the fence: Joe,
Richard Carlsson, Kostis, … who are not on the OTP
team, but deeply enough involved that it can
sometimes be hard to make out whether they speak
for the Team or not. In case of doubt, it's best to ask
for clarification and generally assume they don't.

BR,
Ulf W

Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com

[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

[Michael Turner]

On Fri, Jun 8, 2012 at 6:55 PM, Ulf Wiger <u...@feuerlabs.com> wrote:
>
> On 8 Jun 2012, at 09:19, Michael Turner wrote:
>
>> If I submitted a patch to the seq_trace documentation so that it
>> mentioned that seq_trace implements Lamport clocks, and it got
>> rejected with "we're still thinking about how to work that fact in,
>> maybe we'll have something in the next release," I think I'd end up
>> writing Lamport to say, "Can you *believe* these people?"
>
> Up to this point, I thought you were on a roll with clear,
> insightful and respectful discussion not least about the
> problems of understanding each other in writing, and
> conveying ideas through documentation.
>
> I can understand that certain points can get lost in a long
> and heated thread, so let me clarify a few things:
>
> - I don't work for Ericsson (as also apparent from my sig)

Ulf, at no point in that particular paragraph did I mention you by
name. We didn't exactly bury the hatchet, so it's not like you're
digging it up. But you are picking it up.

> - I don't vet patches on OTP. [....]

I never suggested you did.

> - Whatever changes *I* would like to see to seq_trace, are

>  my own ideas; [...]

Nothing I wrote up there about getting seq_trace documentation to
mention that it implement Lamport clocks could reasonably be construed
as your own idea, particularly since you initially seemed pretty hazy
in your response my statement that seq_trace implements Lamport
clocks.

Specifically:
"... many of the inputs that *actually* informed the implementation
were either confidential or proprietary enough to be of no interest to
the people reading the manuals."

You stressed "*actually*". To me, this strongly implies that Lamport
clocks -- whether they came in as a recommendation by Erlang/OTP as a
"better forlopp tracing", or because of a customers request for them
(in the other version of two as-yet-unreconciled versions of events)
-- did not "inform the implementation." Are they in there? Then there
was some kind of "accident." Or "coincidence." Which seems ridiculous,
since it's pretty obvious from citations in the open literature by
half a dozen Erlang/OTP people that they already knew what Lamport
clocks were.

> In this particular case, the most relevant passage of our
> long discussion should be Gustav Simonsson (who *does*
> represent OTP) saying that your patch was welcome:

If you mean specifically the idea of a patch mentioning that seq_trace
implements Lamport clocks, I have yet to see that from Gustav.

He wrote that documentation patches are (generally) welcome.
Obviously, that's no guarantee of the acceptability for any particular
one.

And I have it (second-hand from you) that he has himself thought of a
good place for this mention, in the seq_trace documentation. To which
I replied: if he's got a good idea for that, why doesn't he just do
it?

I mean, c'mon, this is on the web. It's not like you have to do a
whole print-run of some dead-tree reference manuals to fix it today.
And every day that the Lamport clock pseudocode sits there in the
seq_trace documentation is one more day when Erlang/OTP looks like
it's plagiarizing the idea of a major computer scientist.

As far as I can tell, NOBODY at Ericsson has, in writing, said
directly, "We need to fix that." Until then ....

> The only concrete comments you've gotten this
> time from OTP have been words of encouragement: submit
> a patch, and it will be accepted as long as it improves the
> documentation - not a single hint that they are planning
> anything else for seq_trace.

And I've already responded to that: "improvement" is in the eye (and
to some extent, the imagination) of the beholder. So long as it's part
of some internal Ericsson mythology that seq_trace only reiterates
Lamport clocks as a technique invented independently (and
concurrently, if not earlier) in "forlopp tracing", the response can
always be: "we invented that, probably before Lamport thought of it,
we don't have to credit anybody else, and some of our customers still
think we invented it anyway, so leaving it unmentioned is what works
best for Ericsson AS A BUSINESS."

Until I hear directly from Erlang/OTP people otherwise, I have to keep
that possibility open in my mind. Especially since both you and Robert
Virding seem to have been under this impression, if you aren't still.

> We have no reason to think
> that they are, but now would of course be a good time
> to say so then. :)

I'm all ears.

> There are others who are actually on the fence: Joe,
> Richard Carlsson, Kostis, … who are not on the OTP
> team, but deeply enough involved that it can
> sometimes be hard to make out whether they speak
> for the Team or not. In case of doubt, it's best to ask
> for clarification and generally assume they don't.

I hope it doesn't have to go to lawyers for approval. I mean, whether
forlopp tracing, at any point in its evolution, did or did not include
Lamport clocks ... is that actually something you can't reveal under
NDA? The mind boggles. If it's in there, the fact that it's also a
technique in the open literature from around the same time would seem
to argue that there's no big deal (in NDA terms, anyway) in telling
people. Likewise if it's *not* in there -- you don't even have to
divulge details of what IS in there -- you just issue a denial.

I can think of reasons why a corporation might be cagey on an issue
like this. None of them are terribly complimentary to the corporation.

-michael

[Ulf Wiger]

On 8 Jun 2012, at 12:46, Michael Turner wrote:

> On Fri, Jun 8, 2012 at 6:55 PM, Ulf Wiger <u...@feuerlabs.com> wrote:
>>
>> On 8 Jun 2012, at 09:19, Michael Turner wrote:
>>
> Ulf, at no point in that particular paragraph did I mention you by
> name. We didn't exactly bury the hatchet, so it's not like you're
> digging it up. But you are picking it up.

No, actually, I'm not. I complemented you for your tone and
interesting content in that thread, but did have some comments
on this particular statement. If I mistakenly thought I detected
*you* picking up the hatchet, and it was not so, I apologize.

> Nothing I wrote up there about getting seq_trace documentation to
> mention that it implement Lamport clocks could reasonably be construed
> as your own idea, particularly since you initially seemed pretty hazy
> in your response my statement that seq_trace implements Lamport
> clocks.

I suggest we don't revisit that discussion, esp. in this thread.

Robert's comment, I think, described it well:

[Robert:]
> I really think there are two issues here: what they are, or what
> they are commonly known as; and the generating idea behind them.

I'm sure there is much more that could be said to expand on
that, and I could give some other examples of where mixing
up purpose and implementation in the crafting of API and
docs can lead to problems (the 'ets' module, for one), but
I don't think I will, since you and I seem to differ completely
on what the purpose of seq_trace is, what the word 'tracing'
(and more so 'sequence trace') actually implies, so I think
we would just continue to talk past each other.

>> In this particular case, the most relevant passage of our
>> long discussion should be Gustav Simonsson (who *does*
>> represent OTP) saying that your patch was welcome:
>
> If you mean specifically the idea of a patch mentioning that seq_trace
> implements Lamport clocks, I have yet to see that from Gustav.

That quote came as a response to me saying:

[Ulf:]
> In this case, I'm pretty sure [a reference to Lamport clocks]
> could be worked in without harming readability, but it is of course
> perfectly possible to use seq_trace without understanding, or even
> being aware of the existence of, Lamport clocks.
>
> The OTP team is known to accept patches to the documentation,
> so please feel free to contribute to a more helpful way to describe
> the tracing support. I'm sure it would be universally appreciated.


If Gustav meant something other than the obvious interpretation
that you were most welcome to insert an advanced example
describing how seq_trace implements Lamport clocks, and
how that knowledge can help you make good use of them, he
should hasten to clarify that.

> And I have it (second-hand from you) that he has himself
> thought of a good place for this mention, in the seq_trace
> documentation. To which I replied: if he's got a good idea
> for that, why doesn't he just do it?

No, first-hand from Gustav, as he replied in the thread,
cc to the list. Also, his comment made it clear that he invited
you to expand on the topic - not just insert a one-liner.

> As far as I can tell, NOBODY at Ericsson has, in writing, said

> directly, "We need to fix that." Until then ….

What I was trying to convey with my last post was that you
have actually received more indication that your patch
will be accepted than most people who have submitted
documentation patches have.

If you want even more confirmation before doing anything,
I understand that. That was another thing I tried to convey.
Nobody expects you to put in the time and effort to improve
Ericsson's documentation. I have decided to not make a
number of patches, since I didn't have the time, and didn't
feel confident that they would be accepted.

But that is your decision. It was suggested in another
comment that you have spent more time debating the
issue than it would have taken you to prepare the patch
and submit it. While that is probably true, well, so have I.
Meta-discussions are also important, perhaps sometimes
even more important than what the docs actually say.

Really, Michael, it would be great if you could write up
a good advanced example for seq_trace, with references
to relevant research etc. Whether you do it as a blog post
or as a documentation patch, really doesn't matter much.
You can do both, even.

Sequence trace deserves more use, and any tutorials or
additions to the docs that can help that are a great
addition.

> And I've already responded to that: "improvement" is in the eye (and
> to some extent, the imagination) of the beholder. So long as it's part
> of some internal Ericsson mythology that seq_trace only reiterates
> Lamport clocks as a technique invented independently (and
> concurrently, if not earlier) in "forlopp tracing", the response can
> always be: "we invented that, probably before Lamport thought of it,
> we don't have to credit anybody else, and some of our customers still
> think we invented it anyway, so leaving it unmentioned is what works
> best for Ericsson AS A BUSINESS."

To me, this is a big strawman you're building, but let's try not
to revisit that. For those interested, the debate, and more, is in
the list archive.

> I hope it doesn't have to go to lawyers for approval.

Nothing ever goes to the lawyers for approval, since the
only answer you ever get is "no". ;-)

> I mean, whether
> forlopp tracing, at any point in its evolution, did or did not include
> Lamport clocks ... is that actually something you can't reveal under
> NDA? The mind boggles.

Again, an amazing misrepresentation of what I
(or someone else?) have said.

What I did try to explain was that there is only so much I can
tell, as a former employee, of what went on at Ericsson. Even
when I worked there, I was not allowed to reveal internal
project or product details without approval. When I worked
there, I could of course have picked up the phone and asked
some old-timers what the real story was. Now, I can't.

Why you find this either disturbing or strange is beyond me.
Besides, it has no bearing on whether the seq_trace docs
can say that they implement Lamport clocks - Kenneth has
already said they do. If you do write a patch, and it's rejected,
it cannot possibly be for that reason.

> I can think of reasons why a corporation might be cagey on
> an issue like this. None of them are terribly complimentary
> to the corporation.

I suggested a reason earlier in this mail: the people at the
OTP team have lots on their plate and, right or not, don't
see this as a terribly important issue. Chances are, they are
even too busy to follow this thread in any detail.

(Come to think of it, that goes for me too. Whatever more there
is to say, I have exceeded my time quota, and I'm sure many
on the list would like to see this discussion end.)

BR,
Ulf W

Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com

[Michael Turner]

On Fri, Jun 8, 2012 at 7:36 PM, Ulf Wiger <u...@feuerlabs.com> wrote:
>
> 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.

http://en.wikipedia.org/wiki/Wikipedia:Database_download

> 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.

MediaWiki makes it fairly easy to establish (perhaps with a single
template invocation in the article footer) a way to see every previous
"official release" version of a given article.

Here, for example

http://en.wikipedia.org/w/index.php?title=Erlang_(programming_language)&oldid=465840644

is the version of the Wikipedia article about Erlang from particular
instant in time. I picked it out of the History page for the article.

http://en.wikipedia.org/w/index.php?title=Erlang_(programming_language)&action=history

See the links in the tabs of any Wikipedia article, if you've never
poked at them before.

The tab called "edit" is particularly powerful, I find.

> 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.

"Even"? The Github wiki strikes me as kind of crude, to be honest.
Probably because it's based on a "strong VCS", which isn't necessarily
the the right substrate. (But good enough for Github purposes. I admit
I haven't looked very closely at it yet.)

> 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.

"Improvement" is in the eyes of the beholder. To me, just being able
to fix a grammatical error in under a minute, and have the rest of the
world see it shortly after I hit "submit", is a vast improvement over
the status quo.

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

I don't see the value-added in cloning an entire wiki, except in the
standard model of revision flow where everything leads to a release
date. Wikis are: fix and release a single page, right now.

Right now there's a page that makes Erlang/OTP look like it's
plagiarizing Leslie Lamport. I want to fix it and release it right
now.

If you want release dates for the wiki, you can warn people of the
release date, start locking down pages and even whole namespaces, and
letting in only a few emergency edits as required, then declare what a
snapshot made on the release day the "version" of the wiki for a given
*software* release. Right after the release, you can start loosening
up again, not least so that individual wiki articles can reflect fresh
reports of the more important new bugs in the new releases of the
modules they document.

We all want the perfect, zero-cost system, right now.

What you can get in reality: good, cheap, soon - pick any two.

Admittedly, "good" is in the eye of the beholder. My "good" might not
be yours. But beware premature judgments of "bad". I'm hearing a lot
of "wikis are trash", "wikis can't do this," "wikis can't do that."
Not to get all Mitt Romney on you, but wikis are people. Including
people with designated powers and responsibilities.

Wikipedia can be edited by anybody, and tries to cover everything. For
an Erlang/OTP wiki that's totally inappropriate. You might instead
parcel out editing rights only to a few dozen people outside Ericsson,
and limit the range of topics to articles on released software plus
methodology outlines like OTP Design Principles. MediaWiki doesn't
have the most advanced access control system in the world. But it can
do that. So can other wiki packages. The older ones still in use have
been evolving for about 17 years now, since Ward Cunningham put up the
Portland Pattern Repository

http://en.wikipedia.org/wiki/Portland_Pattern_Repository

in 1995, in the first wiki.

So if you say, with very little experience editing and managing wikis,
"they can't do X", there's a very good chance you're wrong.

-michael turner

[Michael Turner]

On Fri, Jun 8, 2012 at 9:04 PM, Ulf Wiger <u...@feuerlabs.com> wrote:
>
> On 8 Jun 2012, at 12:46, Michael Turner wrote:
>
>> On Fri, Jun 8, 2012 at 6:55 PM, Ulf Wiger <u...@feuerlabs.com> wrote:
>>>
>>> On 8 Jun 2012, at 09:19, Michael Turner wrote:
>> Nothing I wrote up there about getting seq_trace documentation to
>> mention that it implement Lamport clocks could reasonably be construed
>> as your own idea, particularly since you initially seemed pretty hazy
>> in your response my statement that seq_trace implements Lamport
>> clocks.
>
> I suggest we don't revisit that discussion, esp. in this thread.

And then what do you do? You start revisiting that discussion.

> Robert's comment, I think, described it well:
>
> [Robert:]
>> I really think there are two issues here: what they are, or what
>> they are commonly known as; and the generating idea behind them.

"Generating idea" isn't a well-defined term. So I disagree: this
doesn't really say much of anything, because there's apparently no way
(under your NDAs) to distinguish the supposed "generating idea" from
what Lamport clocks are "commonly known as": Lamport clocks.

Lamport clocks are integral to the seq_trace API. The wording of the
documentation makes that very, very clear. The only "beta" caveat is
about possible *interface* changes.

End of story.

> I'm sure there is much more that could be said to expand on
> that, and I could give some other examples of where mixing
> up purpose and implementation in the crafting of API and
> docs can lead to problems (the 'ets' module, for one), but
> I don't think I will, since you and I seem to differ completely
> on what the purpose of seq_trace is, what the word 'tracing'
> (and more so 'sequence trace') actually implies, so I think
> we would just continue to talk past each other.

You say we "differ completely", but you base your differences on
things you say that I can't know because you can't tell me: customer
requirements generated under NDA. This makes no sense. If seq_trace
actually directly reflects customer requirements, I'd say it's pretty
obvious that the customer wanted (among other things) Lamport clocks.
Perhaps they expressed them as, "we have clock skew problems in our
distributed system, and we need some way to correctly sequence our
traces in spite of that." Lamport clocks are a simple, classical
solution to that problem. If that customer (and others) are using that
solution, all YOUR talk of possible alternative implementations is
moot: you'd be introducing an incompatibility.

You might opine otherwise, but since you can't tell me the difference
between the customer requirement and what the seq_trace documentation
says (two things that, at times, you've equated, more confusing
still), you might as well be talking about some divine inspiration not
communicable to mere mortals like me.

> If Gustav meant something other than the obvious interpretation
> that you were most welcome to insert an advanced example
> describing how seq_trace implements Lamport clocks, and
> how that knowledge can help you make good use of them, he
> should hasten to clarify that.

That's your idea of "the most obvious interpretation"? I don't know
how I could have made myself clearer: I've REPEATEDLY suggested adding
four words - "seq_trace implements Lamport clocks."

There's no need to "insert an advanced example describing how
seq_trace implements Lamport clocks." The documentation ALREADY
DESCRIBES HOW IT IMPLEMENTS LAMPORT CLOCKS. I want to see credit where
it's due, because (a) that's the right thing to do, and (b) it gives
people who already know what Lamport clocks are the advantage of
instant familiarity.

Which I've said at least twice before.

>> And I have it (second-hand from you) that he has himself
>> thought of a good place for this mention, in the seq_trace
>> documentation. To which I replied: if he's got a good idea
>> for that, why doesn't he just do it?
>
> No, first-hand from Gustav, as he replied in the thread,
> cc to the list.

A bland and vague solicitation for "improvements" still leaves room
for interpretation of the term "improvement." (As I've already said
probably three times now.) If giving credit to Lamport is finally
judged to not be an improvement, then Gustav's solicitation is NOT a
specific, explicit request for that crediting of Lamport.

> Also, his comment made it clear that he invited
> you to expand on the topic - not just insert a one-liner.

First things first: stop making the seq_trace documentation look like
plagiarism. In four words. Gustav replied with dozens of words when he
himself could have just added four to the documentation.

>> As far as I can tell, NOBODY at Ericsson has, in writing, said
>> directly, "We need to fix that." Until then ….
>
> What I was trying to convey with my last post was that you
> have actually received more indication that your patch
> will be accepted than most people who have submitted
> documentation patches have.

No, what I've received is a lot of words with no definite commitment.
What is so hard about being direct and saying, "Yes, the documentation
should say that seq_trace implements Lamport clocks"?

[snip long passage]

The issues here are so basic.

-michael turner

[Ulf Wiger]

On 8 Jun 2012, at 17:05, Michael Turner wrote:

> So if you say, with very little experience editing and managing wikis,
> "they can't do X", there's a very good chance you're wrong.

…sure, as with everything. And indeed I explicitly said "I won't
say that it *can't* be done with wikis, …"

As it happens, I do have experience editing and managing wikis,
and while I was perfectly able to view the history of individual pages,
and could also bring up an older revision of a particular page, I found
the lack of *baseline support* a distinct disadvantage for some uses.

For example, when we were doing iterative development, and using
wiki pages to reflect the architecture, usage and installation
instructions, as well as the state of the project, the wikis usually
ended up reflecting only the most recent state - anything else was
simply too hard. We could reflect milestones across modules in
the code and in the issue tracker, but the wiki pages kept floating
on top. That's sometimes fine, but in the case of OTP, I personally
want to be able to browse around in a consistent set of pages for
the particular release I'm using.

The wiki used in that particular case was Redmine's wiki.
I have experienced use of other wikis, e.g. MediaWiki, in
past development projects. They were great for keeping up
with peripheral stuff - how to set up test environments, useful
tricks, etc. I think OTP could use the wiki on github more.

The reason why I brought up the github wiki was that it obviously
should be able to do this, since the underlying storage is a git
repository, and github offers the ability to browse a tagged
version of source code repositories. If they did the same for the
wiki, I'd have my baseline support.

(I document my own code with edown, which lets github render
edoc generated as markdown. It has the advantage that I can
browse documentation online that's consistent with the code
in the same view - not at all revolutionary, of course, but still
convenient.)

There used to be a wiki for Erlang: Trapexit. It is currently down.
Some people found it extremely useful, and others didn't. Some,
who would have been able to correct mistakes and add useful
insight, didn't want to create an account, log in and do the edits,
so we had to contact them, ask for their opinion, and try to relate
their knowledge on the wiki and forums. Others abused the
service and had to be locked out.

ESL has said that they are working on a new community site.
Hopefully, we will all get to see it soon.

BR,
Ulf W

[Michael Turner]

On Sat, Jun 9, 2012 at 12:38 AM, Ulf Wiger <u...@feuerlabs.com> wrote:
>
> On 8 Jun 2012, at 17:05, Michael Turner wrote:
>

[snip]

> There used to be a wiki for Erlang: Trapexit. It is currently down.
> Some people found it extremely useful, and others didn't. Some,
> who would have been able to correct mistakes and add useful

> insight, didn't want to create an account, log in and do the edits, ...

Or couldn't. And were entirely blameless for that. I should know.

I don't really care who I offend with the following comment: if
TrapExit is dead now, it killed itself.

I wanted to fix things on it immediately. I tried to create an
account. I couldn't figure out how. There was a sign-up page with a
form with a header that said something like, "If you want to create a
new account, start here." Followed by some form fields, which I filled
out -- but without getting a new account notification.

Here's what the problem was:

Somebody had decided that it was totally cool webby design to not have
links indicated graphically. You had to move your mouse around the
text and IF it happened to intersect linked text, *then* the
underscoring (or whatever) would make it evident there was a link.

And somebody had made the above "here" in the vague instructions the
link to the *real* way to make an account. But when you issue a vague
"here's how" command to the reader, with some form-fields to fill in
immediately following, you're saying that "start here" means "fill out
the form fields below," not "click on this link which doesn't even
look like a link unless you are lucky enough happen to move the mouse
across it." Those who were lucky enough wouldn't remember having any
trouble signing up. Those who weren't lucky enough would have had
nothing but trouble. And who needs trouble?

Dumb, dumb, dumb. It took me forever to convince the one web admin
contact I could get a response from that this was confusing as hell.
Actually, I'm not sure he ever quite got it.

People: go with the defaults. Follow basic web usability guidelines as
you start departing from the installation defaults. Familiarize
yourself with those guidelines if you haven't yet. Most of those
guidelines will tell you that linking the word "here" is at best very
informal style. Most of them will also tell you that links should be
obvious.

This signup-page screwup was far from the only confusing thing about
TrapExit, but in terms of bringing in new users to edit the wiki into
shape, it was certainly the worst. Who knows how many people tried
several times, as I did, to make a new account, only to say, "screw
it, something's broken here, these people don't know what they're
doing, it's not worth the effort." And moved on.

As I remember, I finally figured it out by viewing the HTML source,
after an admin insisted there was absolutely nothing wrong with the
page -- he'd just tested it himself.

Laugh if you like, but these kinds of snags can add up to more
frustration than any volunteer wants to deal with.

-michael turner

[Ulf Wiger]

On 8 Jun 2012, at 17:51, Michael Turner wrote:

> Perhaps they expressed them as, "we have clock skew problems in our
> distributed system, and we need some way to correctly sequence our
> traces in spite of that." Lamport clocks are a simple, classical
> solution to that problem.

No (or, if they asked for that, I'm not aware of it. The OTP team
can correct me if I'm wrong, but that was not the impetus to seq_trace.)

I will try one more time.

Tracing a sequence, as in "our system handles a thousand call
setups per second, and if we turn on a trace on all of them, we
will not only learn nothing - we will kill the system. We need a way
to trigger trace output on *one* session in the midst, and have
that trigger 'contaminate' processes as the request is passed
around in the system, and then, obviously, turn off, so we get
only what we asked for, and nothing more".

Effectively, automatically selecting trace output so that it looks
as if we traced everything and ran only one single call through
the system (which is what most people resort to).

If we call it "session trace", does that make it clearer?

Obviously ordering (sequencing) is *one* part of the problem,
for which Lamport clocks are a great solution. But the part where
tokens act as "probes" whizzing through the system activating
trace output selectively, is part of trying to reduce the amount
of trace data generated.

A large part of the complexity of the tracing subsystem in Erlang
comes from the need of the user to be able to define, ad-hoc,
just the right filters so that one can get useful trace output without
killing the system. While you can accomplish a "session-specific"
trace just using pattern-matching on function calls, this quickly
becomes unwieldy. Usually, you just want to enable a wide trace,
to include all important calls, but *only* for the one session you
decide to trace - not for the perhaps hundreds or thousands of
other sessions that may touch the same process.

For this, the trace patterns in the tracing subsystem can match
on function call parameters and dynamically set and clear
trace tokens.

Rather than 'independent' of the standard tracing, I would
say that sequence tracing is 'orthogonal'. The standard trace
is great for tracing on a small set of functions or modules, or
showing all activity in one or a few processes. But in large
systems under commercial load, doing any kind of tracing is
really scary. Some Erlang old-timers are known to explain
how they took down entire mobile networks by carelessly
setting up a wrong trace.

This is my take on this area. In most practical uses, the
ordering one gets from timestamps is perfectly fine (for
tracing - *not* if one really wants to ensure that the trace
reflects the exact causal order. The hardest problem in
the scenario I describe is avoiding killing the node or
at least getting so much trace data that any analysis
of it becomes prohibitively hard.

That seq_trace makes use of Lamport clocks is an added
bonus, and at least the tools in OTP, like e.g. ttb and et,
should take advantage of this whenever possible. As it
is now, they don't (or I missed it, which is also a possibility).

Is this all clear from the seq_trace manual? No.
It's easy to get the idea that it was created for a different
purpose entirely, and even people who seek it out wanting
to do exactly what I describe above, tend to turn away
frustrated. But it's a hard problem to solve, and I'm not
saying that the current support is sub-par. If I had a clear
idea of how to improve it, I would have submitted patches
long ago. What I did to try to improve things was work to
get ttb's support for saving useful trace patterns and
replaying them later, more stable and better documented.
This doesn't relate to seq_trace as much as to the ability
to manage trace tokens through trace patterns.

It's badly named. It should definitely not speak of
"sequential tracing". I'm pretty sure "sequence"
came out of "förlopp", which basically means "a
sequence of events". The function of a "forlopp" in AXE
is that it the smallest single unit of failure. It can be aborted
and re-run, like a transaction.

Does all this preclude adding a reference to lamport
clocks in the seq_trace manual? Obviously not.

If it bugs you so much, write a patch and submit it.
I agree that it will cost OTP as much to vet your patch as
it would for them to put the sentence in themselves, but
if it's not a priority to them, and it is to you, you know what
to do.

But it sounds as if you are putting seq_trace to good use,
in a way that is different from what I describe above.
Boiling this down to an example would be a great contribution.

BR,
Ulf W

Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
http://feuerlabs.com

[Michael Turner]

Ulf, I've been using it seq_trace for months. I know what it does.
It's pretty clear what it's *typically* for. That's not to say there
shouldn't be a tutorial.

If Lamport clocks are (part of) what the customer asked for, there's
no mystery hiding behind the NDA. What they asked for has already been
been capital-D Disclosed -- in the seq_trace document. It just hasn't
been given its proper name there.

> Rather than 'independent' of the standard tracing, I would
> say that sequence tracing is 'orthogonal'.

I'm glad I wasn't drinking anything when I read that, because it would
have spurted out of my nose. But I guess I get it anyway.

[snip a long explication of what I already thought was pretty obvious]

> Is this all clear from the seq_trace manual? No.

If someone wants to write detailed use-cases for seq_trace, I'm all in
favor of that.

I just want to get Lamport the credit he's due, while also helping to
inform those who already know of his work that they can get Lamport
clocks out of Erlang/OTP, if they need them. That can be done in four
added words, words which nobody seems to willing to explicitly commit
to, much less actually add themselves. No, I have to write a patch.
Otherwise it won't happen. Weird. As if the *ethical* onus here is not
on the provider of the documentation.

> That seq_trace makes use of Lamport clocks is an added
> bonus, and at least the tools in OTP, like e.g. ttb and et,
> should take advantage of this whenever possible. As it
> is now, they don't (or I missed it, which is also a possibility).

Or everybody missed it, because when they searched the documentation
on "Lamport clocks", under the very reasonable assumption that someone
writing them up would call them what they're actually called, nothing
turned up.

And I fear it's because of ego: people at Ericsson still think they
invented this everything in seq_trace first, maybe somewhere in
forlopp tracing ....

> Is this all clear from the seq_trace manual? No.
> It's easy to get the idea that it was created for a different

> purpose entirely ...

I have no idea why you think that. Among my first thoughts, upon
encountering seq_trace, was, "hey, that's cool: if I've got zillions
of messages flying around, and I'm only interested in those that
originate from one process (or a few of them) and kick off yet others
in a kind of chain reaction, seq_trace helps me reduce overhead. Yes,
I have uses for that."

Then I discovered that it implements Lamport clocks. I was even
happier. In fact, it implements almost nothing *but* Lamport clocks --
which implicitly include tokens being passed between processes that
might be looking at skewed clocks - so almost everything you describe
falls out as the simplest default choice of what messages to record.
But so what?

We agree that it has a bad name -- I think if you're going to call it
a trace package, call it "par_trace" or something. But so what?
Computer technology is full of misnomers.

> But it sounds as if you are putting seq_trace to good use,
> in a way that is different from what I describe above.
> Boiling this down to an example would be a great contribution.

Um, no. I'll be trying to use seq_trace to verify a partial ordering
of multiple default inheritance operations driven by spreading
activation in (natural) language network descriptions. Somewhat as
described by Richard Hudson in his last two books on Word Grammar.
Except that he's a little scared of doing the inheritance in a
spreading-activation style (which is already very important in his
theory), and I'm trying to find out whether he's actually right to be
scared. I don't think he is - I think the win is always much bigger
than any possible loss. I've convinced him of other (less ambitious)
operational simplifications for his theory, and maybe I can nail this
one, too.

It's kind of an annoying testing problem, because you don't care about
the order or precise timing for some events, but the order definitely
has to be right in other ways - i.e., your basic partial order, which
is something Lamport clocks ("happened before" relation) gives you.
It's not like, "I sent this message, I should see the following exact
sequence of resulting messages." Then it would be easy. Or easiER,
anyway.

I *could* write these tests as simply a process that sends activation
messages to some language-network concept nodes (each of which is a
process), then send an "inherit" message to the concept node that's
supposed to inherit, and wait around to see what it inherits. The
problem with that: if it doesn't get the right traits, I'll have no
idea why. seq_trace is cool because it can tell me what happened. It's
also cool for regression tests because if the right traits are
inherited (and other things happen in the right order) the test
silently passes. It's also pretty scalable from what I can tell. I can
parallelize my tests. That's important because human languages are big
and will require a lot of test cases.

But I understand the need for a tutorial for more typical uses of
seq_trace. This whole thread is, amazingly, is just a lot of topic
drift from somebody asking "What's the equivalent of Hello World for
Erlang tracing?" For seq_trace, at least in a testing role, the Hello
World should be a kind of unnaturally simple problem like this:

Make sure that when process A sends a message X to process B,
B sends a message Y to process C as a result,
and C receives it.

So you provide a tracer that sends A an acknowledgement if it sees C
get Y after A sends X to B. Process A waits in a "receive/until". The
test fails if that receive/until times out. And in fact a lot of my
tests so far are just a process sending "inherit" up the inheritance
chain(s) in the network of concept processes and then waiting for the
tracer to report that a certain message arrived at some concept node.
I'll need to go beyond this, soon enough. But it's good enough for
where I am now.

-michael turner

[Ulf Wiger]

On 8 Jun 2012, at 20:01, Michael Turner wrote:

> But I understand the need for a tutorial for more typical uses of
> seq_trace.

Sure, but if you could condense what you're doing into a simple
example, I think that would be very, very cool. It's not a typical
problem for telecoms systems, but in a way that's the best
kind of help community members can give. Ericsson should
manage to explain the mainstream problems in telecoms, but
Erlang is used for many other things nowadays, and the docs
should reflect that.

[Richard O'Keefe]

On 8/06/2012, at 7:19 PM, Michael Turner wrote:
>>>> Our first technical writer, Kennita Watson, was technically competent.
>>
>> Did you read that sentence?
>
> Yes. I read it as "technically competent *as an engineer*", because
>
> (a) she has degrees in computer science (from Stanford and MIT at that
> -- facts I recalled about her the instant I read her name), and
>
> (b) what followed was an anecdote that I didn't quite get, because
> somebody (you?) wrote "Never let an engineer write the documentation"
> and I thought you were agreeing with the point -- you certainly didn't
> contradict it immediately.

She wasn't an engineer >>>ON OUR PROJECT<<<.
And that's what I was agreeing with.

>
> So at first I read your comment on her work as saying that she'd
> suggested changes in the documentation to make things more
> documentable from *her* point of view (as an engineer), but that they
> were still things that the customers didn't understand.

Not a bit of it. Our customers were *also* programmers; her value was
precisely that her perspective was their perspective. I did say it was
Prolog; what other kind of person uses a Prolog system?

> Such people are admittedly as rare as hen's teeth in the more
> quotidian livelihood of tech writing. The Kennitas of that world are
> rare enough. (I think she was only sidelined because of some injury --
> I'm not sure. I'd kill to make use of her on a project myself, if she
> were still available.)

"Sidelined"? She moved to a bigger company (which is still around,
unlike Quintus) with a larger customer base and more to write about.
I never asked, but they could certainly have _afforded_ to pay her
more than we could. Everyone I was close to at Quintus wanted her to
stay.

>
> Which takes me back to my agenda: what's the *practical*, *dirt-cheap*
> way to *eventually* get better quality docs for Erlang/OTP?

Step 1: fix the tool chain so I can build the documents.

I've annotated the erl_docgen document; there's something that needs
fixing on every page. I am keen to send in patches, but I can't do
that until I can build the documents.

> And their edits can easily be reviewed.

And now we come to the crux of the matter. It's the *review* process.
That takes time and effort and management, and it's not at all clear
to me what, if anything, makes a wiki easier to manage than the current
setup. The mere existence of a wiki is no guarantee of good reviewing.

The great thing about the current scheme is that edits are reviewed
BEFORE they are adopted, but we're promised that they'll be reviewed
quickly. With a Wiki, bad stuff goes in, and if you're lucky it will
be reviewed and eventually be taken out, but there _is_ that window
where the bad stuff is there.

I won't mentioned which Wikipedia page it was, but the one Wikipedia
page I ever did anything to was one which contained several gross
factual errors and had for months.

But there is also the fact that wikis tend to lead to lots of bits
all over the place and a hell of clicketyclicketyclickety for almost
anything. Recently I've been wandering round the Tizen "documentation".
Not a good advertisement for "Web documentation".

One thing the current tool chain gets almost right is that it really
does generate man pages and HTML and PDF from the same sources. I
have a shelf of printed and bound Erlang manuals.

> People will say a lot of silly things about wikis and their governance
> until they gain more direct experience of maintaining them. In that,
> wikis are like anything in life.

My comments about wikis are based entirely on my experience of actually
trying to get basic information out of wiki "documentation" for several
projects. "Like anything in life", wikis obey Sturegon's law.

>> Wikis do not solve this problem, they exacerbate it.
>
> You're prone to sweeping generalizations about wikis based on no
> direct personal experience of editing them, from what I can tell.

I have edited one page in one wiki, no wait, three pages in two.

But editing is simply not the issue.
My comments are based on too much painful experience of trying
to *USE* wikis edited by others.
I don't see why only people who edit wikis count here.
I think that people who *USE* documentation matter, and that
having tried to *use* about a dozen wiki-"documented" open source
projects and finding intense frustration is relevant.

I find the suggestion that only experienced editors of Wikis are
competent to judge the usability of wikis outrageous.

>> How high *is* the bar? Have you ever submitted a documentation patch
>> and had it rejected?
>
> I've never submitted a documentation patch.

Ah! You've never tried, but you just _know_ that the barrier is high.

> You hate amateurs.

No I do not. I *am* an amateur.

Let's go back to Quintus. While we had technical writers,
the "engineers" often *originated* documentation. It just had to
go through technical writers before customers saw it. And it was
the same for code: with one notable exception, all changes that
affected what customers saw had to be reviewed before final
acceptance. And that one exception was the single dumbest thing
Quintus ever did, and sadly, one of the most copied.

The chief problem with the existing Erlang documentation is that
it was released without an adequate review of the language.

> I can understand that. But the experts fail sometimes too.

It's not professional vs amateur. It is review-before-release
vs post-release-review-if-ever.

By the way, if you want to see an appalling example of editing,
take a look at the ANSI Smalltalk standard. The 5th draft was
full of glitches, almost all of which survived in the published
standard. Even being-published-by-ANSI was no guarantee of
adequate proof-reading.

>
> If I submitted a patch to the seq_trace documentation so that it
> mentioned that seq_trace implements Lamport clocks, and it got
> rejected with "we're still thinking about how to work that fact in,
> maybe we'll have something in the next release," I think I'd end up
> writing Lamport to say, "Can you *believe* these people?"

Ulf Wiger is not in charge of reviewing changes to the Erlang
documentation. The people who _are_ in charge might well be
perfectly happy with adding "Since its first release, seq_trace
has relied on Lamport clocks [ref], but it is not guaranteed
that it will always do so."

Right now, I'm reading someone complaining about the extreme
difficulty of putting in a sentence and making up a story about
what he'll say to someone when rejected

WHO HAS NOT TRIED IT.

Try it. *Then* resume this conversation.

No, wait. *I've* just posted a change to erlang-patches.

> Good ideas, I'm sure. I'm using Erlang to implement a computational
> linguistics framework, so I'm definitely keen on those sorts of
> solutions myself. But automating a task to get "better than nothing"
> shouldn't be the goal here. This is supposed to be documentation by
> professionals, for professionals.

And professionals use good tools. INEX isn't running "link-the-Wiki"
any more because you need to able to compare what you can do with a
"gold standard", and it turns out that while the Wikipedia is
*copiously* linked, it isn't always *well* linked, and when programs
did badly at matching what was there, it was sometimes because the
programs were doing better.

As for unimplemented EEPs, that comes back to a documentation issue,
namely that the BEAM is not (yet) adequately documented.

[Michael Turner]

RIchard: "I did say it was Prolog; what other kind of person uses a
Prolog system?"

To name one: the linguist I've been working with, Richard Hudson, who
tried to implement his theory of language in Prolog in the early 90s.

"> "Sidelined"?  She moved to a bigger company (which is still around,
> unlike Quintus) with a larger customer base and more to write about."

http://www.linkedin.com/pub/kennita-watson/1/321/a19

Kennita's most recent resume entry there:

too much experience
Long Term Disability
July 2005 – Present (7 years) Sunnyvale, CA

I haven't worked since 2005; the purpose of this entry is to get
LinkedIn to stop asking me for a current position.
---

Maybe she's only joking about the disability part.

> And now we come to the crux of the matter.  It's the *review* process.
> That takes time and effort and management, and it's not at all clear
> to me what, if anything, makes a wiki easier to manage than the current
> setup.

I don't know either, because I don't know Ericsson Erlang/OTP
documentation patch review processes.

For how it would work in a wiki, try starting at this link

http://en.wikipedia.org/w/index.php?title=Richard_O%27Keefe&diff=489842048&oldid=489773645

and keep clicking "Previous edit". I think this interface makes it
pretty easy to tell that a small, simple edit (which is most of them,
and which would be most of them, in what I propose) is in fact
correct. If it's not, note the "undo" links -- very often, "undo" just
works without fuss.

So if this is the "crux of the matter", maybe a wiki would actually
make documentation patch review and acceptance *easier* than it is now
at Ericsson: a reviewer would spent most of his time clicking "next"
or "previous" links, looking at diffs, deciding whether to "undo" (and
mostly deciding not to). Whatever the reviewer has left is the
official new revision for that page, for the upcoming release. 90-99%%
of edit reviews will take a few seconds, if they are limited to
typos/grammar and wikilinking what hadn't been linked before. The more
problematic content-related ones might take between minutes and hours.
Or, in the case of "seq_trace", perhaps weeks, as it generates panicky
questions to legal staff like, "Have we ever charged a customer any
technology license fees on the basis of a claim that the algorithm
here was somehow our own invention? And what's the company's potential
liability if so?"

> The mere existence of a wiki is no guarantee of good reviewing.

*Eyeroll*. As if I said that it was. As if I haven't, in fact, spoken
extensively about issues of administration already. More strawmen like
these and I'll be buried under several bales worth of straw.

> It's not professional vs amateur.  It is review-before-release
> vs post-release-review-if-ever.

A false dichotomy. There's also "this wiki reflects recent changes by
volunteers since the last snapshot for release X; these changes
haven't necessarily been officially reviewed and/or approved by anyone
at Ericsson, though they will be reviewed before the next release,
which is planned for around <date>. If you want the official version
for release X, here's a link to the snapshot of this article that went
out at the same time."

> "Like anything in life", wikis obey Sturegon's law.

Oh? If all existing Erlang/OTP documentation were put in a wiki, as I
propose, would it be crap just by being in a wiki, from day one of the
wiki being live? Possibly so, if you consider the current
documentation crap.

> I find the suggestion that only experienced editors of Wikis are
> competent to judge the usability of wikis outrageous.

The usability of a *given* wiki? Or the fitness-for-purpose of wiki
software for helping maintain Erlang/OTP documentation, from an
administrative point of view? It's only the latter issues that concern
me here, and it's on those issues that you keep saying things I find
either incomprehensible or flatly wrong.

-michael turner

Yep. It happens. Here's one of my recent corrections:

http://en.wikipedia.org/w/index.php?title=Greenland_ice_sheet&diff=prev&oldid=495435286

But that's what you get in *Wikipedia*, which is trying to be an
encyclopedia for everything, editable by anybody: breathless idiots
making order-of-magnitude numerical errors. I've written on this
thread SEVERAL TIMES about how the editor membership of any Erlang/OTP
wiki could be sharply limited, to help insure good-faith,
well-informed edits. Are you EVER going acknowledge that?

> But there is also the fact that wikis tend to lead to lots of bits
> all over the place and a hell of clicketyclicketyclickety for almost
> anything.  Recently I've been wandering round the Tizen "documentation".
> Not a good advertisement for "Web documentation".

I'm not talking about wikis that "just grow". I'm talking about a wiki
that starts, on day one, with the current Erlang/OTP documentation.
That should have been abundantly clear to you by now. If you're still
responding to any other scenario, it can only be out of neglect of the
arguments I've already made, and perhaps out of a need to get
complaints about some *other* wikis off your chest. If I added my
*own* complaints about lousy wikis, we'd be here for months. Can we
move on?

> One thing the current tool chain gets almost right is that it really
> does generate man pages and HTML and PDF from the same sources.  I
> have a shelf of printed and bound Erlang manuals.

Gosh, it's too bad you can't do that with MediaWiki, and never will be
able to, because it's a big mess written by a bunch of retards who
would never even think of doing something that useful. I mean, what if
you wanted assemble a PDF out of a bunch of Wikipedia articles and
make a book? You can't, because ... um ... oh wait:

http://en.wikipedia.org/wiki/Help:Books

*Sigh*.

> Ulf Wiger is not in charge of reviewing changes to the Erlang
> documentation.  The people who _are_ in charge might well be
> perfectly happy with adding "Since its first release, seq_trace
> has relied on Lamport clocks [ref], but it is not guaranteed
> that it will always do so."

If they were "perfectly happy" saying that, I'd find it be pretty
disturbing. The "Beta" disclaimer speaks only about possible *minor*
changes to the *interface*, not any *major* change to core
functionality. And Lamport clocks are unmistakably part of the core
functionality of seq_trace. Try actually reading the seq_trace
documentation, Richard, if you want to weigh in on these issues.

> Right now, I'm reading someone complaining about the extreme
> difficulty of putting in a sentence and making up a story about
> what he'll say to someone when rejected

Right now, I'm reading that someone else's ethical imperative --
giving credit where it's due -- is somehow *my* responsibility, rather
than that of the providers of the documentation in which credit isn't
currently given. And those who maintain the documentation will only
accept my contribution if it "improves" the documentation in their
eyes -- eyes that seem still prone to see Lamport clocks as an
independent, concurrent invention by Ericsson, with no proof of that
belief. I think I can be excused my suspicions.

[OvermindDL1]

On Sat, Jun 9, 2012 at 1:30 AM, Michael Turner
<michael.eu...@gmail.com> wrote:
> /* snip all */

Is there not a wiki out there that by default shows a 'published'
copy, but lets you see the current head with another click, and lets
you make changes to the head, and an authenticated
manager/editor/something/special can clean changes and vet it to
publish as the new default view, preferably with a list of 'heads that
do not match default' page so they know what to look at?

[Jan Burse]

Michael Turner schrieb:
> The usability of a*given* wiki? Or the fitness-for-purpose of wiki

> software for helping maintain Erlang/OTP documentation, from an
> administrative point of view? It's only the latter issues that concern
> me here, and it's on those issues that you keep saying things I find
> either incomprehensible or flatly wrong.

There is an further issues with client-server based
collaborative tools such as a wiki. You need to have
all the time a working internet connection. This is
ok if you are doing work from a location with a stable
and fast connection.

But sometimes the check-out and check-in model is
superiour to the client-server based model. Especially
if you have intervalls where you don't need a lot of
interaction with peers and/or where connectivity is not
possible.

Since all your artefacts are local after check-out
you will also experience a much faster responsiveness
of your tools. Since one is allowed a smoother editing
one usually has a higher productivity. Also before
check-in again changes are often automatically
compressed.

There are a couple of integrated development environments
either free or for a few bucks that integrate well with
version management, and that also provide graphical diff
tools. These diff tools can be used for many things like
merge conflict resolution, change reviews, change promotion,
etc.. Here is a typical diff view:

http://codingbone.files.wordpress.com/2010/11/picture-2.png

I am currently involved in changing a wiki solution
with a Prolog driven automated kind of proof reading
into a check-in and check-out solution. Most probably
the outcome will be a hybrid, but in the future the real
editing will be done kind of offline. And the proof reading
load will be done locally and not anymore on the server,
resulting in much more speed.

But prerequisit for all this is also a kind of locality
respectively predicatabilty of the involved data, i.e.
pages. Low frequency higher grain check-out is only
possible if one can predict what module one will need
for a particular task at hand. In a memex like environment
where one is about to follow unpredictably links, this
is difficult.

On the other hand in a hybrid solution, the wiki could
still be used to browse accidential links. And I guess
in a structured work environment it will be also possible
to delineate modules. But I am not yet sure how well
things will work. Problem are always highly shared modules
which have a lot of updates. Check-out and check-in can
also slow down an organization. But good automated
merging might help here.

Bye

[Michael Turner]

On Sat, Jun 9, 2012 at 6:06 PM, OvermindDL1 <overm...@gmail.com> wrote:
> On Sat, Jun 9, 2012 at 1:30 AM, Michael Turner
> <michael.eu...@gmail.com> wrote:
>> /* snip all */
>
> Is there not a wiki out there that by default shows a 'published'
> copy, but lets you see the current head with another click, and lets
> you make changes to the head, and an authenticated
> manager/editor/something/special can clean changes and vet it to
> publish as the new default view, preferably with a list of 'heads that
> do not match default' page so they know what to look at?

I haven't looked. But here's how to approach such questions: wiki
software is software. So ask yourself, "Could software do this?" If
the answer is "yes, then not-too-surprisingly often, there is already
a wiki (or an extension thereof) that does it.

One reason why the idea might not be implemented: it isn't actually a
good idea. In this case, it might not be.

Wikis improve by evolution of a *current* version. They are more
likely to improve if the current version is the most frequently seen
version. If the default page for any article is instead the
"published" copy, rather than the true *current* version, and if users
need to notice and click a special link to get any contributed updates
to that copy, you are asking volunteers to do more work and giving
them more frustration. People like me who often want to fix errors
will see them in the "published" and locked-down copy, and click
through to the wikified version to navigate to the point of error,
only to discover, all too often, that somebody has already corrected
it.

Better to put current version first, with a disclaimer, and make the
"release version" on which it's based easily available through a
prominently featured link.

-michael turner

[Michael Turner]

On Sat, Jun 9, 2012 at 6:27 PM, Jan Burse <janb...@fastmail.fm> wrote:
> Michael Turner schrieb:
>>
>> The usability of a*given*  wiki? Or the fitness-for-purpose of wiki
>> software for helping maintain Erlang/OTP documentation, from an
>> administrative point of view? It's only the latter issues that concern

>> me here, and it's on those issues that you [Richard O'Keefe]

>> keep saying things I find either incomprehensible or flatly wrong.
>
>
> There is an further issues with client-server based
> collaborative tools such as a wiki. You need to have
> all the time a working internet connection.

[snip]

I haven't done offline wiki editing. However, as with almost any idea
that seems both possible in software and a good idea, there are
solutions, at least in the case of MediaWiki. Here's what looks like a
relatively simple one, a project started all the way back in 2004:

http://search.cpan.org/~markj/WWW-Mediawiki-Client/bin/mvs

Other packages listed here

http://en.wikipedia.org/wiki/Wikipedia:Text_editor_support

might provide offline support. I don't know.

-michael turner

[Richard O'Keefe]

On 9/06/2012, at 7:30 PM, Michael Turner wrote:
>
> http://www.linkedin.com/pub/kennita-watson/1/321/a19
>
> Kennita's most recent resume entry there:
>
> too much experience
> Long Term Disability
> July 2005 – Present (7 years) Sunnyvale, CA
>
> I haven't worked since 2005; the purpose of this entry is to get
> LinkedIn to stop asking me for a current position.
> ---
>
> Maybe she's only joking about the disability part.

I'm not a member of LinkedIn, so I am unable to read her profile.
She may well not be joking; one of the highly innovative people
in the Prolog community, Lee Naish, pretty much dropped out of
sight for similar reasons. He's a really nice person too.
(And Melbourne is an Erlang-friendly University: the Mercury
language/system has a back end that generates Erlang. If Lee
hadn't become ill, he might have contributed a lot to Erlang.)

>
>> And now we come to the crux of the matter. It's the *review* process.
>> That takes time and effort and management, and it's not at all clear
>> to me what, if anything, makes a wiki easier to manage than the current
>> setup.
>
> I don't know either, because I don't know Ericsson Erlang/OTP
> documentation patch review processes.
>
> For how it would work in a wiki, try starting at this link
>
> http://en.wikipedia.org/w/index.php?title=Richard_O%27Keefe&diff=489842048&oldid=489773645
>
> and keep clicking "Previous edit". I think this interface makes it
> pretty easy to tell that a small, simple edit (which is most of them,
> and which would be most of them, in what I propose) is in fact
> correct. If it's not, note the "undo" links -- very often, "undo" just
> works without fuss.

That actually tells me a lot about review processes, and it is damning.

• 12:19, 29 April 2012 (diff | hist) . . (-4)‎ . . Richard O'Keefe ‎
• 12:19, 29 April 2012 (diff | hist) . . (+13)‎ . . Richard O'Keefe ‎
• 12:18, 29 April 2012 (diff | hist) . . (+67)‎ . . Richard O'Keefe ‎
• 23:22, 30 March 2012 (diff | hist) . . (-39)‎ . . Stiliyan Petrov ‎ (→‎External links)
• 20:53, 13 February 2012 (diff | hist) . . (+50)‎ . . Syd Barrett ‎

There are several edits there, purportedly by me, of a version that claims
I'm the cousin of some footballer, which I am not.

- The information is untrue.
- The purported author is not the real author.
- The subject is alive and readily reachable and
the changes were not verified.

I'd like to thank 'Gadfium' who apparently corrected the article, but I
have no idea who Gadfium is. When I tried to send feedback saying that
I'd like to thank Gadfium for the correction, I got a "Form submission
error" with no indication of what the error actually was.

In my wildest dreams I couldn't have asked for a better example of a
Wiki going wrong. And what the history features of Wikipedia actually
guarantee is that the wrong information will be discoverable forever.

> So if this is the "crux of the matter", maybe a wiki would actually
> make documentation patch review and acceptance *easier* than it is now
> at Ericsson:

I do not see any advantage to be gained by making
rapid acceptance of untrue information with forged credentials easy.

[Michael Turner]

> There are several edits there, purportedly by me, of a version that claims
> I'm the cousin of some footballer, which I am not.

SInce I've written over and over on this thread about how becoming an
editor should be a much more restrictive process than Wikipedia's
(which is something you can do in MediaWiki - it offers fairly
fine-grained access control.) I can only take the complaint you offer
as a sign of either serious amnesia ()get that looked at) of serious
disrespect for anything I have to say.

> I'd like to thank 'Gadfium' who apparently corrected the article, but I
> have no idea who Gadfium is.

You could post here, on his talk page

http://en.wikipedia.org/wiki/User_talk:Gadfium

if you were thankful. If you need to know who he is, you could ask
there, and he might send you private e-mail.

In any case, this is all irrelevant for our discussion, since policy
of any Erlang/OTP wiki could easily include (and probably should
include) a rule that everybody editing must be identified by their
real-world name. This rule could be enforced by putting a human being
in the loop of signup, someone who makes sure that the e-mail address
sent as part of signup is that of a real person, and that this real
person sent that application for editorship.

> In my wildest dreams I couldn't have asked for a better example of a
> Wiki going wrong.

Then you don't have much experience at all with editing wikis, because
much worse stuff happens all the time. It needn't happen with an
Erlang/OTP wiki, for reasons I've explained over and over, in earlier
message, and which you apparently either can't remember (get that
looked at, the amnesia may be effecting your work too) or choose to
ignore (can't help you with that problem.)

> I do not see any advantage to be gained by making
> rapid acceptance of untrue information with forged credentials easy.

Nor do I. MediaWiki, and all wikis worth of the name, provide
administrator dashboards from which one can enforce requirements on
membership. As you can see, the need for it is obvious. And in fact,
employed often enough. I've been part of the process of banning people
from editing, including IP blocks. In one case, it involved someone
who made legal threats against me, and only for revising an article on
a controversial subject to be more accurate (in case you're wondering
why most editors - not me, but most - choose anonymity.)

Again, you're falling back on "wikis suck because I found something
bad." You're not asking, "Why does this bad thing happen, and is there
anything to be done to prevent it?" In fact, these problems are quite
manageable, and Wikipedia, in the interests of gathering the largest
possible membership, leaves editing quite open. It also means some
information is unreliable at one time or another. Anyone who reads
Wikipedia without keeping that in mind is simply a fool.

-michael turner

[Richard O'Keefe]

On 11/06/2012, at 4:53 PM, Michael Turner wrote:
>> In my wildest dreams I couldn't have asked for a better example of a
>> Wiki going wrong.
>
> Then you don't have much experience at all with editing wikis,

I have repeatedly said that I have little experience of *editing*
wikis and that my opposition is based on the serious frustration
I've repeatedly experienced *using* them. Apparently you also
suffer from amnesia.

>
> Again, you're falling back on "wikis suck because I found something
> bad."

I have never made any claim that general.
I say that *documentation* wikis are in my experience bad;
far far worse than the existing Erlang documentation.

I've actually pointed to Wikipedia as unusually *good* in my
experience. I may be wrong about that:

http://catless.ncl.ac.uk/Risks/26.79.html#subj6.1

60% of Wikipedia entries about companies contain errors
When respondents attempted to engage editors through
Wikipedia's "Talk" pages to request factual corrections
to entries, 40 percent said it took "days" to receive a
response, 12 percent indicated "weeks," while 24 percent
never received any type of response. ... Of those who were
familiar with the process of editing Wikipedia entries,
23 percent said making changes was "near impossible."
Twenty-nine percent said their interactions with Wikipedia
editors were "never productive."

That's citing

http://www.sciencedaily.com/releases/2012/04/120417113527.htm?utm_source=feedburner&utm_medium=feed&utm_campaign=Feed:+sciencedaily+(ScienceDaily:+Latest+Science+News)

which has a number of links that are very positive about Wikipedia;
this particular article was based on Marcia W. DiStaso. "Measuring
Public Relations Wikipedia Engagement: How Bright is the Rule?"
Public Relations Journal, Vol. 6, No. 2

and while I was initially apprehensive because our library's
e-subscription lapsed, it turns out the PDF of that article is at

http://www.prsa.org/Intelligence/PRJournal/Documents/2012DiStaso.pdf

The title of the RISKS article is a little misleading:
out of the people surveyed, 60% of those whose companies had a Wikipedia
entry, who knew it had, and who had checked it, had found factual errors
worthy of correction. We have no information about the error rate in
the entries for companies whose PR people _don't_ know it has a Wikipedia
page (25% of the PR people surveyed said they didn't know if their
company had a Wikipedia entry or not, which should give their employers
pause for thought). 21% of the people who reported errors had found
spelling errors, which gives _me_ pause for thought about the utility
of a Wiki as a device for correcting spelling.

The paper has some sobering figures about corrections being undone.

"Half of respondents who have either directly edited or used the talk
pages to make edits indicated that they believe the process of making
changes to a company or client’s Wikipedia article is typically time
consuming (n=275), but 27% stated that it was easy (n=152), while
23% said it was near impossible (n=127)."

There's a followup in RISKS

http://catless.ncl.ac.uk/Risks/26.89.html#subj18

by someone who is more concerned about one UK PR firm who were caught
adding positive information about their clients than about other
companies' difficulty getting wrong information correctly.

> You're not asking, "Why does this bad thing happen, and is there
> anything to be done to prevent it?"

No, and that's because I'm the wrong person to do so.
That's *your* role in this debate.

> In fact, these problems are quite
> manageable, and Wikipedia, in the interests of gathering the largest
> possible membership, leaves editing quite open. It also means some
> information is unreliable at one time or another. Anyone who reads
> Wikipedia without keeping that in mind is simply a fool.

The thing is, the more you talk about "management", the less a Wiki
sounds substantively different from the system we have right now.
A restricted pool of editors? We have that now: the main difference
is that you expect to become one of them. Low barrier to entry?
We have that now. The one major difference is that (like many of
the PR professionals surveyed in that paper) I would be happiest
with review-before-publication, where you seem to be happy with
review-after-publication-if-ever.

I repeat something I've said before, in case you have forgotten.

Nothing stops you setting up an Erlang documentation Wiki right now.

[Michael Turner]

On Tue, Jun 12, 2012 at 7:02 AM, Richard O'Keefe <o...@cs.otago.ac.nz> wrote:

>> Again, you're falling back on "wikis suck because I found something
>> bad."
>
> I have never made any claim that general.
> I say that *documentation* wikis are in my experience bad;
> far far worse than the existing Erlang documentation.

Again: if all the existing Erlang/OTP documentation were suddenly in a
wiki, word for word, would it be "far, far worse" than the existing
documentation?

That, and the quality of the ensuing administration, are the only two
things that matter for this discussion. NOT that somebody added some
incorrect information about you to your Wikipedia biography.

> I've actually pointed to Wikipedia as unusually *good* in my
> experience.  I may be wrong about that:

It's incredibly bad in some places, and very good in others. That,
again, is a function of an administrative choice: Wikipedia can be
edited by anybody, even anonymously. High-interest articles tend to
have a lot of watchers to help maintain quality. Low-interest articles
can have crap in them that nobody notices for months.

> http://catless.ncl.ac.uk/Risks/26.79.html#subj6.1
>
>        60% of Wikipedia entries about companies contain errors
>        When respondents attempted to engage editors through
>        Wikipedia's "Talk" pages to request factual corrections
>        to entries, 40 percent said it took "days" to receive a
>        response, 12 percent indicated "weeks," while 24 percent
>        never received any type of response. ...

This is ridiculous. If you think a factual correction is required to a
Wikipedia article, DO IT YOURSELF. If you have the editing skills
required to alter a Talk page, you probably know enough to make the
change you think is necessary in the article itself.

Afraid to touch an article? Then don't get involved in the first
place. One of the Five Pillars of Wikipedia is "Be bold."

http://en.wikipedia.org/wiki/Wikipedia:Be_bold

If you approach Wikipedia in something other than the spirit Wikipedia
itself strongly encourages, you shouldn't complain about the results.
Editors with a strong interest in articles set up watchlists mainly
*for* the articles, not so much for the article Talk pages. You want
attention to a problem in an article? Apply your own attention first:
make what you think is a fix. Who knows? You might actually be right!

> ..... Of those who were

>        familiar with the process of editing Wikipedia entries,
>        23 percent said making changes was "near impossible."
>        Twenty-nine percent said their interactions with Wikipedia
>        editors were "never productive."

This is also a ridiculous criticism of Wikipedia when, if anything,
it's to Wikipedia's credit. Go look at Articles for Deletion

http://en.wikipedia.org/wiki/Wikipedia:Articles_for_deletion

And that's just just the tip of the iceberg of the generalized
egomania out there, an obstacle that Wikipedia is always trying to get
past while staying as open as possible. A dismayingly high proportion
of those who get "familiar with the process of editing Wikipedia
entries" are people who familiarized themselves in order insert
self-serving information of one kind or another, including entire
articles about themselves, their non-notable music careers, their
non-notable companies, their non-notable self-published novels. Even
those who actually DO clear Wikipedia's bar of notability (and their
fans) will insist on trying to add information to the resulting
articles that doesn't qualify as properly sourced or written from a
neutral point of view.

http://en.wikipedia.org/wiki/Wikipedia:Neutral_point_of_view

And how likely is it that a survey of *PR* "professionals" (corporate
flacks) who tried to edit Wikipedia would have tried to do it without
violating

http://en.wikipedia.org/wiki/Wikipedia:Neutral_point_of_view

and guidelines about Conflict of Interest?

http://en.wikipedia.org/wiki/Wikipedia:Conflict_of_interest

This is a function of Wikipedia's access control, which is pegged at
the most liberal end of the spectrum. It's also possible to set up a
MediaWiki-based wiki that permits nobody except a tiny coterie of
administrators to contribute edits. And there is a range of
possibilities in between, including customized access control
algorithms for those who know PHP/MySQL. (Yeah, yeah, I know: that
choice of technologies is a bug in itself. Whatever.)

> The title of the RISKS article is a little misleading:
> out of the people surveyed, 60% of those whose companies had a Wikipedia
> entry, who knew it had, and who had checked it, had found factual errors
> worthy of correction.

Wikipedia has a number of areas where it's weak. In my experience,
except for the more prominent companies, business is one of them. Bad
information about companies is one syndrome in that topic area.
Another much more serious one, however, owes to the PR people surveyed
in the paper you cite: companies using Wikipedia for self-promotion.

None of which is relevant to this discussion -- unless perhaps
Ericsson wants to claim that it invented Lamport clocks, without any
supporting independent references for the statement.

No, we're talking about what's *theoretically* possible in putting the
Erlang/OTP documentation into a wiki, under access control policies
that would presumably be acceptable under the terms of licensing by
Ericsson, and that would favor contributions of reasonable quality.
I've already suggested one strategy for access control, and I've
repeated it several times since. Find it and tell me what's wrong with
it, if you want to criticize it.

> ... 21% of the people who reported errors [in business articles] had found

> spelling errors, which gives _me_ pause for thought about the utility
> of a Wiki as a device for correcting spelling.

That's probably because when you can see from the first paragraph that
the Wikipedia article is yet another puff-piece that got in there
somehow, you might as well just go to the company website. (And let
your eyes glaze over reading that.)

When people search on a general topic ("bees", "galaxies"), the
Wikipedia page often head the rankings. And the #1 result gets most of
the attention. When people search on a company, they usually they get
the company website first. Since so many Wikipedia articles about
companies are transparently nothing but plagiarized PR (often
self-plagiarized) from company websites, I'm not surprised that they
get so little copyediting attention, for any added information beyond
the PR.

> The paper has some sobering figures about corrections being undone.
>
> "Half of respondents who have either directly edited or used the talk
>  pages to make edits indicated that they believe the process of making
>  changes to a company or client’s Wikipedia article is typically time
>  consuming (n=275), but 27% stated that it was easy (n=152), while
>  23% said it was near impossible (n=127)."

"Sobering"? I'm laughing like a hyena.

I'm pretty sure that the overwhelming majority of those frustrated
23%-29% were trying to do something Wikipedia actually rules against:
stating "facts" without reliable-source backup.

http://en.wikipedia.org/wiki/Wikipedia:Identifying_reliable_sources

And that's not even getting into "neutral point of view" and "conflict
of interest" issues.

Let's say that the Wikipedia article on Erlang/OTP were to say, on
nothing more than the strength of belief on the part of some Ericsson
veterans or current employees, that Lamport clocks were invented as
part of tracing, in the late 70s, and for the AXE series of switches.
I.e., that there was no citation to anything qualifying under
Wikipedia's Reliable Source rules. In that case, the statement should
be deleted. Anybody who insisted putting it back into the article
based only on their own personal opinion could, if they were
sufficiently insistent, end up being banned from editing Wikipedia.
Would they report that they were "frustrated"? Probably. SHOULD they
have been "frustrated"? Probably.

Even when something is true, it's not enough. In general, it has to be
reported elsewhere, independently. I did some edits on

http://en.wikipedia.org/wiki/Brad_Cox

and contacted him about getting some reliable sources for certain
points in his resume (since he always seemed rather unsung to me.) He
asked, "What do you do when you yourself are the only source?" I
replied saying that I didn't doubt him personally, but that the rules
existed for good reason: the incredible level of dishonesty and
egregious self-promotion that happens on Wikipedia if you don't have
such rules.

>> You're not asking, "Why does this bad thing happen, and is there
>> anything to be done to prevent it?"
>
> No, and that's because I'm the wrong person to do so.
> That's *your* role in this debate.

I don't need to ask "Why does this bad thing happen?" Bad? I've
already seen it all. Fought it all.

>> In fact, these problems are quite
>> manageable, and Wikipedia, in the interests of gathering the largest
>> possible membership, leaves editing quite open. It also means some
>> information is unreliable at one time or another. Anyone who reads
>> Wikipedia without keeping that in mind is simply a fool.
>
> The thing is, the more you talk about "management", the less a Wiki
> sounds substantively different from the system we have right now.
> A restricted pool of editors?  We have that now

FINALLY you acknowledge a point I've made repeatedly: most of your
concerns about bad information getting into a wiki can be addressed by
MediaWiki access control, which Wikipedia only uses on a case-by-case
basis.

> the main difference
> is that you expect to become one of them.

Actually, quite the contrary, at least on the specific point of
getting the seq_trace documentation to mention that it implements
Lamport clocks if only I submit a patch. The internal corporate
self-mythologizing on this point appears to be quite strong, if the
views of two former employees are any indication.

> Low barrier to entry? We have that now.

Eye of the beholder again.

In the Erlang/OTP documentation I find errors in grammar, punctuation
and spelling that never seem to get fixed. There are points in the
text where a link would be enormously helpful, but those links never
seem to get added. If the barrier to entry for fixes is so "low", as
you claim, why weren't these things fixed long ago?

> Nothing stops you setting up an Erlang documentation Wiki right now.

Unless if violates the Ericsson license terms.

And then there's this: the discouraging impression that highly
intelligent people can nevertheless reject ideas for reasons stemming
almost entirely from their own ignorance and prejudices, and who will,
having taken such a stand, go cherry-picking all subsequent evidence
they present, from of irrelevant contexts if necessary, and who will
quickly change the subject to one those picked cherries when shown
evidence that they are wrong on a given point.

Case in point: you.

-michael turner

[Dave Cottlehuber]

On 12 June 2012 07:49, Michael Turner <michael.eu...@gmail.com> wrote:

[snip]

I value this list above almost all other ones that I subscribe to, for the high
quality of contributions and the care & time put into the responses. It's a
model technical community.

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.

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?

A+
Dave

[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