Automation is important in most software development (or adjacent) roles. Most of us have probably been in the situation of dealing with too many things manually, that should have been automated long before. Worse, often the manual “process” isn’t much of a process at all, and the task in question is a daunting, possibly anxiety-ridden problem.
There is probably plenty of desire to automate the process, but never enough time or business buy-in.
This is my personal philosophy towards automating things, in two “easy” steps.
The actual place this documentation lives is unimportant - wiki, text file in your repo, even a word document (although - blech). This document has a couple of important attributes:
Any part of the process that entails typing stuff into a computer - be it running shell commands, visiting particular URL’s, grabbing files from a file share should be plain text you can copy and paste from1.
Any “variable” that is used in multiple places should be easily replaceable for that cut and paste. Either by making it super obvious:
git commit -m "Releasing NEW_VERSION"
git tag vNEW_VERSION && git push --tags
or even better, by turning it into an environment variable or similar:
export NEW_VERSION=v1.2.3
git commit -m "Releasing $NEW_VERSION"
git tag v$NEW_VERSION && git push --tags
Is the date part of your process? Never require that it be manually typed - it’s prone to typos or confusion over the format.
export RELDATE=$(date +%Y-%m-%d)
As far as possible, this process should be “idiot-proof” and could be done by the least experienced team member.
Letting people unfamiliar with the process run the process has an unexpected benefit - deficiencies in the instructions (“Oh, I thought everyone knew how to frob the gizmo”) quickly become evident, and the documentation can be improved.
Now you get to actually write some code. The documentation you wrote above? It’s pseudocode, possibly almost actual code with just some polish needed.
Even better, there’s no need to tackle the entire thing in one go. Choose the pieces which are maximally “cut and paste” and just automate those first. Update the documentation “now just press the ‘frob’ button”. You’re one step closer to full automation, but you’ve already made everyone’s life easier.
Be aware that many systems will still manage to fuck up your carefully selected quotation marks, spaces and commas and blithely replace them with completely-different-but-visually-similar unicode equivalents. As a general rule, the more “enterprise” your document storage system is, the more likely this is. This will make your cut & paste process a fraught experience. ↩︎