/index.xml

Executable Documentation

script

Every team has manual procedures or checklists that they haven’t gotten around to automating yet. Sometimes there are branches and special cases to keep track of as you go. Procedures/checklists are frustrating because they’re focus-intensive yet require very little thought. They demand our full attention, but our attention isn’t rewarded with interesting problems or satisfying solutions – just another checkbox checked. Procedures like this are called a slog.

Slogs are ripe for automation. We know that a computer could do it better than we can, and with less tendency toward practical drift. However, automating slogs feels like an all-or-nothing proposition. Maybe we could write a script to handle step 2, or step 5, but that wouldn’t really make the procedure any less cumbersome. It would lead to a proliferation of single-purpose scripts with different conventions and expectations, and you’d still have to follow a documented multi-step procedure for using those scripts.

This perception of futility is the problem we really need to solve in order to escape from these manual slogs. Here’s an approach that works. It’s called “executable documentation”.

Almost any slog can be turned into executable documentation. Executable documentation is a script that encodes the instructions of a slog, encapsulating each step in a function. For example we could write the following executable documentation script:

#! /bin/sh
# ------------------------------------------------------------------------------
# Copyright (c) 2014 Dan Stroot
# All rights reserved.
# ------------------------------------------------------------------------------
# NAME:           example.sh
# PURPOSE:        example of executable documentation
# VERSION:  1.0   Initial version
# ------------------------------------------------------------------------------
set -e

# Default settings
PROGNAME=$0
VER="1.0"

step_1 () {
    echo "Do step 1, press (y, enter) when complete."
    read -r response
    case $response in
    [yY])
        echo "Step 1 completed.\n"
        ;;
    *)
        echo "Step 1 NOT completed.\n"
        exit 1
        ;;
    esac
}

step_2 () {
    echo "Do step 2, press (y, enter) when complete."
    read -r response
    case $response in
    [yY])
        echo "Step 2 completed.\n"
        ;;
    *)
        echo "Step 2 NOT completed.\n"
        exit 1
        ;;
    esac
}

step_3 () {
    echo "Do step 3, press (y, enter) when complete."
    read -r response
    case $response in
    [yY])
        echo "Step 3 completed.\n"
        ;;
    *)
        echo "Step 3 NOT completed.\n"
        exit 1
        ;;
    esac
}

main() {
    echo "Running: ${PROGNAME}, version ${VER}.\n"
    step_1
    step_2
    step_3
    echo "All Done!"
    echo "Wouldn't it be great if this was automated?"
}

main "[email protected]"

Notice this script doesn’t actually do any of the steps of the procedure! It feeds the user a step at a time and waits for them to complete each step manually. These scripts will have little logic, and make little use of variables. They can also have a .txt filename to ensure that people understand, that first of all, this is a set of instructions for how to do something, which also just so happens to be a valid shell script.

At first glance, it might not be obvious that this script provides any value, but the value is immense. First, these scripts actually do something: they allow storing and updating the state of a process. By having these scripts run in a shell rather than in your head, the current state is stored in a machine, not your brain.

Read On

Digital Business Card

shredded paper

Recently I took on a new role. I was asked for information so that business cards could be ordered for me. I reflected a moment and realized I don’t really use business cards anymore. I decided that I needed a digital way to share my business (and personal) information, and I wanted to be able to control what I share. One of the side benefits of this is I don’t have to share my personal mobile phone number either. The number below is purchased through Twilio and is only used to reply with my digital business card.

You can send a SMS (type anything) to +1 949 333-0466 to try it out.

Read On

I'm OK; the Bull is Dead.

bull

Years ago I read a great article on clear communication. Unfortunately it is hard to find these days. I am reproducing it here for posterity and full attribution.


By Gopal K. Kapur
Computerworld | JUN 21, 2004 7:00 AM PT

Early in my career, when I worked as an engineer, my boss had a process by which the engineering team was expected to report project status. He insisted that we use the following steps, in the specified order:

  1. Punch line: The facts; no adjectives, adverbs or modifiers. “Milestone 4 wasn’t hit on time, and we didn’t start Task 8 as planned.” Or, “Received charter approval as planned.”
  2. Current status: How the punch-line statement affects the project. “Because of the missed milestone, the critical path has been delayed five days.”
  3. Next steps: The solution, if any. “I will be able to make up three days during the next two weeks but will still be behind by two days.”
  4. Explanation: The reason behind the punch line. “Two of the five days’ delay is due to late discovery of a hardware interface problem, and the remaining three days’ delay is due to being called to help the customer support staff for a production problem.”

Notice the almost reverse order of these points in comparison with the common reporting style in which team members start with a long explanation of why things went wrong. Using the four steps described above, the project manager learns the most important information first, then he learns supporting information to help complete the story.

Read On

The Polygon of Enterprise Despair

The polygon of enterprise despair

When enterprises see the changes wrought by disruptors in music (Spotify), advertising (Google) or retail (Amazon), they wonder what may be in store for them.

As of this writing, in early 2019 Sears announced it is near liquidation, with a $4.4B bid to keep operating. At the same moment, on the same day, Amazon.com is the most valuable company in the world with an$810B valuation, or 184 times greater.

Prior to Amazon’s founding Sears had everything. Global supply chain, check. Top notch distribution operation, check. System and infrastructure to take orders and handling billing, check. Brand recognition and established customer base, check.

Unfortunately for an incumbent, change is much harder than anyone imagines it to be.

Read On

Hammer Factories

the Internet

There is a post from 2005 by Benji Smith in the old (and now closed) Joel on Software Discussion Group. It’s titled “Why I Hate Frameworks”. But I know it as “the hammer factory” post. It’s just brilliant, even 13 years later. I am reproducing it here for posterity in case the old Joel on Software Discussion Group ever disappears.

Read On