Communications of the ACM, June 2018, Vol. 61 No. 6, Pages 48-53
Practice: “Documentation Is Automation”
By Thomas A. Limoncelli
“Automation is putting process into code. A bullet list in a process document is code if it is treated that way.”
Let me tell you about two systems administrators I know. Both were overloaded, busy IT engineers. Both had many repetitive tasks to do. Both wanted to automate these tasks. After observing these two people for a year, I noticed that one made a lot of progress, while the other one didn’t. It was not a matter of skill—both were very good software engineers. The difference was their approach, or mind-set.
I would say the successful one had a mindset of always thinking in terms of moving toward the goal of a better automated system. Imagine an analog gauge that points to the left when measuring that a process is completely manual but slides to the right as progress is made toward a fully autonomous system. The developer mindset is always intent on moving the needle to the right.
The less successful person didn’t write much code, and he had excellent reasons why: I’m too busy! The person who made the request can’t wait! I have 100 other things to do today! Nobody’s allocating time for me to write code!
The successful person had the same pressures but somehow managed to write a lot of code. The first time he did something manually, he documented the steps. That may not be code in the traditional sense, but writing the steps in a bullet list is similar to writing pseudocode before writing actual code. It doesn’t run on a literal computer, but you run the code in your head. You are the CPU.
Automation is putting process into code. A bullet list in a process document is code if it is treated that way.
…
Some IT engineers never have time to automate their work. Others have the same time constraints but succeed in creating the preconditions (documentation, code snippets) that enable automation.
As you work, you have a choice. Will each manual task create artifacts that allow you to accelerate future work, or do you squander these opportunities and accept the status quo?
By constantly documenting and creating code-snippet artifacts, you accelerate future work. That one-shot task that could never happen again, does happen again, and next time it moves faster. Even tasks that aren’t worth automating can be improved by documenting them, as documentation is automation.
Every IT team should have a culture of constant improvement—or movement along the path toward the goal of automating whatever the team feels confident in automating, in ways that are easy to change as conditions change. As the needle moves to the right, the team learns from each other’s experiences, and the system becomes easier to create and safer to operate.
A good team has a structure in place that makes the process frictionless and collaborative—plus, management that rewards and encourages the developer’s mindset. Always be automating.
