Software without Process

A software product with undocumented or poorly documented commits and a patchy issue-tracker is akin to a shipping pallet with 100 boxes haphazardly stacked on it, all wrapped up in shipping cellophane. You can see some of the labels and some of them you can’t and some of the boxes definitely don’t even have labels at all.

If it looks like the pallet to the right, then you already know you can’t ship it. That’s an obvious train-wreck of a project that’s going to blow up in everyone’s face. But the picture to the left looks…OK…ish. How do you know if it’s legit? Check the shipping manifest and get out your scanner gun, right?

The shipping manifest on your clipboard has 3 and ½ items on it, none of them really helpful. If you really want to be sure about what you’re shipping, you’re going to have to unwrap the whole thing and look at each box individually, noting it on the manifest if it’s missing — and maybe even opening it up to see what’s actually inside. Maybe it’s even broken and leaking on other boxes, somewhere in the middle of that whole pile.

Maybe someone wrapped it in cellophane to give it the sheen of reliability, but you can’t know for sure. Is it possible that you spend all of the time to dot the i’s and cross the t’s just in order to find out that it was fine, but just drastically under-documented? It’s possible, of course. That’s a risk you take when you try to be professional. The alternative is to become a gambler—shipping something and hoping that it doesn’t come back to haunt you.

A better approach would have been to use a documenting process as you built the product—like engineers rather than cowboys—slowing our awesome selves down a bit, but also—maybe, just maybe—getting faster because we’re more careful and can avoid wasting time on work that doesn’t need to be done.

Documenting the work to be done—e.g. to explain it to other team members—can have the much-appreciated side-effect of focusing you on the work that actually needs doing. This is generally more efficient and satisfying than just shooting out of the gate and doing what you “know needs doin’” and not noticing possible ramifications until it’s too late do anything but react to rather than plan for them.

In the end, you have not only solid, well-designed, and tested software, but also good documentation of what was actually done for a given release, as well as analyses for what was not done and what needs doing in the future. That everything is well-documented enough to implement now means you’ve got half a chance of still knowing what it means in ½ or ¾ of a year when you finally get a chance to plan and implement it.

Who knows? You may never need to work on it again—which is just fine. At least you’ll know what you didn’t implement and why. This is very helpful for that time, in a year or two, when you think of this exact same solution and are maybe too stressed or under too much pressure to remember why you decided against it the first time.

A good software product is not just the product itself, but all of the metadata surrounding it: the documentation, the analyses, the release notes, the roadmap.