Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.

Checklist the Docs

by Daniel Beck

Slides

Flying is safe. Flying is also crazy complex. How is it both of these at once?

The aviation industry has turned a huge complex procedure into a series of checklists and created the safest way to travel. Using the history of aviation as backdrop, Daniel explored the idea of how to deal with documenting things that are too complex to work with.

The checklist solution was found by Boeing. They used a system approach which says that accidents are caused by many small mistakes. This resulted in Boeing realizing they need to help pilots manage the aircraft. This led to the first series of checklists. Today every commercial jet departure uses a checklist.

Checklists have been show to counter failure even with late added complexities. How do we use checklists to make documentation? Unfortunately, there is no checklist for this because the problem is very contextual.

A checklist is a not a to-do list.

A checklist is a completable repeatable unit of work. This talk focused on normal checklists used in routine situations. The other format is non-normal checklists for odd or troubleshooting events.

To make a checklist find a good context, such as:

• a physical threshold
• a routine pause
• a process boundary

Daniel used an example of a well-used checklist for merging private branches in his version control system. This has prevented a lot of clean-up commits.

Choose A Pattern

• Read-Do: Read an Item and Do it
• Do-Confirm: Do the work then use the checklist to verify the work is completed appropriately

Read-Do Version

1. run tests
2. run spellcheck
3. schedule review
4. run merge command

Do-Confirm Version

Note: Context is pre-merge command execution.

• Test passed
• Spellcheck passed
• Review schedule

Task Selection Is Critical

There are two approaches. The first, a standard procedure, lists all tasks required to produce the same output every time. The second, an essential items approach, lists only the essential “killer items.” These are the ones that are absolutely required.

Standard Operating Procedure Approach

• Build completed
• Index entries created
• Tests passed
• Spellcheck passed
• Review scheduled

Essential Items Approach

• Tests passed
• Spellcheck passed
• Review scheduled

The hardest things is to actually use and finish the checklist. Use rewards, rituals and monkey-brain training.

Troubleshooting

1. Are you skipping tasks?

   Re-evaluate the context.

2. Are you starting but not finishing the checklist?

   Make it shorter or split it up. Research says 5-9 items is the optimal length

3. Does the checklist feel pointless?

   Make sure it is checking things that matter and that the process hasn’t changed

4. Is it not catching errors?

   Try adding new task items and new things.

Checklists and Automation

Checklists can verify that systems work, assist with integration, and are useful for prototyping.