Opening Word is Software Development Fail
I’m going to perform a slight experiment on myself in this post. As I type this second sentence, I have only a general idea for a post in mind, and I’m going to go out on a limb and say that this will be a relatively short post. I won’t come back and edit this paragraph if it turns out not to be, however. I’ll just look stupid. I’m going meta here because my posting cadence has slipped and I’m going to aim to combat that by mixing in some relatively short posts that are quicker to write and read. I’ve tried this before, and it’s sort of like a yo-yo diet where I cut back for a bit and then just kind of bloat back out to where I was. Anywho…
Over the course of my career a fairly common thing that I’ve done at a new company is to set up a wiki for collaboration. Almost invariably, this wiki replaces or, at least, aims to replace a series of Word documents. It’s as though there’s some kind of knowledge collection progression that goes, “nothing, README, Word, Wiki (or, perhaps, Sharepoint),” and I make my home at an organization just long enough to say, “hey, there’s a better option than shared drive/source controlled Word documents.” Why is the next step better? Searchability, not needing that “version history” table at the top, sane linking, changing the emphasis to content over styling, etc.
But, I had a thought today that I’d been sort of missing the point all these years. It’s not that wiki isn’t good, by any means, as a collaboration tool, but it’s that I’m often using it to mitigate the symptoms rather than treat the illness. If, as a developer, you find yourself opening Word to document a process, you’ve failed. If you optimize by documenting in a wiki, you’re just failing in a more searchable, sophisticated, and open-source way (unless you use Sharepoint, and then not open-source and maybe not sophisticated… hiyo, just kidding, but kind of not kidding.)
Is this a harsh thing to say? Certainly. Could you argue that I’m link baiting once you hear what comes next? Probably. But I think there’s an element of truth if you allow yourself to de-stigmatize the word “failure” and interpret it without a value judgment. For instance, today, I failed at being someone with 10,000 RSS subscribers to my blog. It’s true, but not damning. Developers documenting things with Word fall into this same category. You’re failing when you do this, and what you’re failing to do is automate.
I’ve blogged about a similar line of thought with code comments in the past. Comments in method bodies are basically developers saying, “I’m going to punt on making this code expressive and just kinda cheat by explaining this mess in English.” So it goes on a broader level with Word documents. Why do you write Word documents, after all? It’s to explain how to setup your development environment or how to perform a deploy. Maybe it’s to document what needs to happen whenever you add a new feature to the code base or in the event that you need to rollback to a previous version of the application. Whatever it is, you’re faced with some kind of procedure and you declare, “there’s a precise sequence of instructions that needs to be executed, and, as a programmer, I’m going to write them in English and use the next poor sap that happens on them as the runtime interpreter.”
I mean, think about it. If your process is defined well enough to merit a series of numbered steps in a Word document, it’s probably defined well enough to automate. Now, it might be that it’d take you three months to automate and 30 minutes to make the Word document. It might be that there are steps you lack the authority or permission to automate (or even do). It might be that you’re making a user manual or API document. There are any number of practical reasons that you’re not some kind of failure as a person for cracking open Word and explaining how to do something with a computer. You’re not a failure, but you have failed. For whatever reason, you’ve failed to automate. So next time you find yourself reflexively starting Word to make some sort of “writeup” about a technical thing, pause and ask yourself, “would automation of this process be possible and worthwhile?” It might not be, but then again, you might be surprised to find that the answer is “yes.”