I recently wrote about tradeoffs in automation. I thought it’d be nice to have a side by side comparison of manually documenting and releasing software, versus automation.
| Manual Documentation | Automation | |
|---|---|---|
| Assumptions | Many implicit assumptions. No incentive to be explicit. Author bias and perspective limit the utility. | Everything is explicit, no assumptions. |
| Culture | This approach fosters a culture of cracking the whip to get results. Since manual documentation is often out of date, it’s rarely useful. Individuals tend to dislike ineffectual work. | Can align incentives to update the automation by making it the only mechanism to release. This encourages everyone to implement practices that make their lives easier. |
| Tools | Only requires knowledge of basic typing skills and a text editor or something like Microsoft Word. | Requires learning new tools, big part of learning curve. |
| Freshness | Often, documents only created and updated after we get burned. Typically a reactive strategy. | Can align incentives to update the automation by making it the only mechanism to release. Typically a proactive strategy. |
| Accuracy | Only way to test the process is by hand. | Can run process with the push of a button, including end to end automated testing of the result. |
| Forgetting | Implicit assumptions fail to be captured and are easily forgotten. Outdated documents means the knowledge remains locked away in individual minds. | Everything is automated, there’s nothing to forget. It’s possible to forget how to use automation tools. But they’re understandable by a larger audience than the nuances of a particular system’s release process. |
| Professionalism | Everything suffers: testing, confidence, tradeoffs, reliable software, rushed work, happy users. It’s simply unprofessional to not adopt some level of automation. It’s as if a doctor were to continue to rely on bloodletting. There aren’t many things we shouldn’t automate if we thoroughly consider the tradeoffs. | Once we grasp the basics of automation and put them in place, new ways of working arise. Things we just couldn’t imagine possible, take almost no effort. Like, releasing a single change to the application, with confidence, in a matter of minutes. |
| Why? | These documents can be versioned, but that rarely happens, especially if formats like Microsoft Word are used. Since these are often updated after the fact, we may forget why a change was made and fail to include crucial comments about rationale. | Automation lends itself well to version control. We can see explicit, individual changes. By writing these in advance of the release, our rationale is still in mind and can be included in our comments. |
| Large Scale Deployments | Not feasible. | A unique case where automation is the only answer. Involves advanced practices, patterns and tools. It’s important not to frame these advanced practices as *best practices* for automation in all situations. We don’t want to detract those with small scale deployments from the other benefits. |