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

[Michael Turner]

On Sat, Jun 9, 2012 at 12:38 AM, Ulf Wiger <ulf@REDACTED> 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

>> 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
>
> Ulf Wiger, Co-founder & Developer Advocate, Feuerlabs Inc.
> http://feuerlabs.com
>
>
>