Checklists for Erlang I

Dr. Atul Gwande set out to study clinical and surgical errors and how to reduce them.

He concluded that many clinical and surgical procedures are so complex that even experienced specialists can’t keep every essential step in mind during the heat of practice.

The cost?

Clinical and surgical mistakes, patient injury, death, lawsuits, ruined careers, and rising healthcare costs.

What to do?

Dr. Gwande’s research led him back to WWII. Boeing Aircraft had developed the B-17 bomber as one of the most sophisticated, high-performance aircraft ever to come off the boards. But, when three men died as result of an early test-flight accident, many argued that the B-17 was just too demanding for human pilots. Influential congressmen argued that the B-17 program should be scuttled. The survival of Boeing itself was at stake.

But Boeing came up with a very simple solution: A checklist. Boeing implemented a simple checklist, then went on to fly 1.8 million hours with 18 B-17s without incident. Eventually nearly 13,000 were built.

I argue that checklists are an answer to an Erlang noobie’s prayers — particularly in the area of user documentation for web frameworks and other relatively complicated applications.

Noobies trip and fall over a relatively small handful of user doc deficiencies:

1) Assumed knowledge – the docs presume users have knowledge or skills that, in fact, they don’t.

2) Missing steps – the docs omit crucial steps.

3) Confusing language – the docs are poorly written or ambiguous.

4) Missing context – the docs fail to mention crucial hardware, software, or software version prerequisites.

The result:

Noobies waste hours trying to untie the Gordian knot. They turn away in frustration. Fine software fails to gather critical mass community. Erlang gets a bad rap.

Over the next few posts I’ll recount my experience in turning above-average Erlang user documentation into a checklist and the surpising results.

Stay tuned.

Advertisement