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.”
[…] Opening Word is Software Development Fail – Erik Dietrich discusses the importance of documentation, and how Word Docs and Wikis are not the ideal way for it to be created. […]
Indeed. Today I was going thru legacy code in an app that goes like this:
return kpiTargetId.ToString() == “-1” ||
DateTime.Parse(fromDate.ToString()) > DateTime.Today ||
DateTime.Parse(toDate.ToString()) > DateRef;
not expressive and no comments.I deal with rubbish like this every f**** day and the previous dev is no longer around. I’m going through gigantic nested if else statements with cryptic variable names and I find myself praying for a comment somewhere. For real!
Depending on how much blowback you’d face, it can sometimes be cathartic in situations like that to say, “welp, I’m just going to delete all of this crap and see what breaks.” (Not necessarily recommended — just satisfying).
wouldn’t you just need to document the automated process then?
Touche. I suppose at some point you have to communicate what you’ve done so that others know what to expect. I suppose I was never explicit about it in the post, but the kind of thing I was picturing is the Word documents that I’ve encountered through my career that contain things like: “(1) Set environment variable foo=”bar” (2) download file baz from the following URL… blah, blah, blah.” So the difference in consuming such a process goes from, “here, newbie, follow this mind-numbing word document” to “here’s a jump drive, newbie, plug it in and double click SetupAllTheDevThings.bat.”
I’m a fan of automating repeating tasks. But you always have to document how this process works and how it could be done by hand, if anything fails. We have a pretty complex jenkins setup to test and deliver software. In the case of an problem on this server, we don’t want to delay our software deployment. So we can do our ‘manual override’ routine. We don’t describe how our nant scripts work. We describe how the process works.
I wonder if it would be possible to have your backup be some different automation. It’s kind of a rhetorical question though. The main thing that inspired me to write this post was musing on the idea that I should always ask myself if I couldn’t somehow automate whatever I’m currently documenting instead of writing the document. In all reality, the answer will often be “no,” I’m sure, but I’m trying to bias myself in favor of automation over documentation.
I think your absolutely right with what you write. Convention over configuration or infrastructure as code for example are all ways to reduce the need to write documentation thats more a checklist than useful information.
[…] Opening Word is Software Development Fail, Erik Dietrich […]
You only fail if you just document, what you could have automated. But no build script tells you WHY it is. Or what design decisions and tradeoffs were involved.
Automate the WHAT, document the WHY.
I’m doing kind of a mental exercise and imagining that I come into a shop with an automated build/deploy on checkin. I think I already know the “why”. I’m not sure such a document would interest me, and the only reason I can imagine wanting to read it is if the CI setup were doing something weird or unexpected (and then a better fix might be to make it not do that). One thing I’ve learned over the years, and I’m saying this as someone who has left a long trail of documents explaining myself, is that people rarely read… Read more »
Many of your posts discuss the importance of getting out of the way of your programmers or making sure they have fewer distractions. For many companies, obsessive documentation is really just to make the organizational leadership feel like they can quantify/explain/justify the work their programmers are doing without the need to understand all the details. In essence, its because they don’t trust their programmers to create a quality product. In these types of organizations, the documentation is one of the “killing cats” parts of the company. For these companies, more documentation will make the problem worse, not better. I’ve worked… Read more »
Your experience mirrors mine (though I’ve never worked at a document management company). These things never being read and being a hindrance rather than a help have both been things I’ve witnessed over and over firsthand. The only way in which I perceive them as not a total loss is when writing them helps the author gain clarity. But honestly, that’s almost never the case since the author is generally being forced to do it by people, process, or both. A lot of times it strikes me as the kind of thing that people do blindly because. while they view… Read more »