Is software the documentation of business process mistakes?

Some time ago, I learned an amusing but insightful maxim:

The user manual is a list of software design mistakes.

(It may have been from The Design of Everyday Things, I don’t remember and a cursory web search hasn’t been helpful.)

Well-designed things may not be perfectly discoverable and consistent and stable, they may not be obvious and familiar, but in general, if something needs a lot of explanation, it may need rethinking.

Note that this does not mean that you can’t introduce something new that needs explaining. But overall, you are seeking economy in the user manual. So you want to introduce as few things that need explaining as possible. And you want your explanations to be as simple as possible. And you want the implications and consequences of those things to be obvious and without lots of caveats.

To borrow a phrase, you don’t want leaky abstractions. Leaky abstractions don’t need much explaining up front, but the caveats and exceptions and trivia you ought to know (like the maximum depth of call stack in some languages) will inflate your user manual into a tome. Well-chosen and well-implemented abstractions, on the other hand, need a little explaining up front, but after that they are ‘discoverable’ and need little or no further caveats.

So the point of the maxim is to seek overall economy of explanation. This is not particularly novel or insightful, of course. The utility of the maxim is remembering that the complexity of the user manual is an imperfect but helpful proxy for complexity of the software.

I have certainly applied that approach to designing things myself: If I need to explain it over and over again, if I need to describe how all of the parts interact and why this button changes the colour unless the current mode indicator is set to resize, in which case it zooms… maybe I need more time designing and less time documenting.

So my teeny bit of advice here is to always think about the user manual when designing something. If it is hard to document, it is hard to use. That definitely goes for code: if it is hard to explain, it is probably hard to maintain. That’s a great argument for writing documentation: The act of documenting something forces you to see it from the other person’s perspective.

I imagine all of us can get together on this. We may disagree on whether Ruby Metaprogramming makes something harder or easier to explain, whether andand helps or hurts, but the basic principle seems robust: if you sit down to explain it, you will get a feel for how it looks to someone who hasn’t been thinking about it non-stop for several days or weeks.

Could software be a list of business process mistakes?

Ken Tilton just wrote an excellent post that touched on this subject from a new angle: “We Can Live With the Way You Handled That”. Ken’s story is entertaining and well worth the full read (I am only going to talk about one element of the post, but his anecdote really illuminates the business software development process: please give it your full attention.)

The thing that struck me like a gong about Ken’s story is that software in business is a kind of documentation for business processes! Business processes are often these gnarly heaps of rules with massive omissions, contradictions, and bits where what people say they do has no relation to what actually happens. Writing a piece of software to augment or automate the process forces people to think hard about the process.

In my experience, good managers know this. Quite often, the real motivation in automating a business process is as an indirect way to force this review. This is why writing business software is called consulting. This is why it rarely works well when outsourced to a firm in another time zone: the problem is not writing 50,000 lines of Java. Nor is the problem writing 7,500 lines of Ruby.¹

The problem is exactly the same problem as writing documentation for a feature: The problem is realizing that if the software to automate a business process is complicated and contradictory and hard to use, then the real cause is a business process that is complicated and contradictory and probably not serving the company well.

Good software has succinct and easy-to-understand documentation. You can’t bring a genius technical writer in to turn a sow’s ear into a silk purse. Likewise, good business processes have succinct and easy-to-understand software automating or augmenting them. It’s the same thing: you can’t bring in a genius software architect to craft silk software for porcine processes.

So in the end, when you are writing a piece of business software and it is gnarly and contradictory and full of exceptions and holes and it is impossible to understand… that may be a sign that you are not writing a very good piece of software. But it may also be a sign that the underlying business process is gnarly and contradictory and full of exceptions and holes.²

You may need to push back on the requirements and foster change in the business. Of course, that may not be possible. Good managers are as rare as good software developers. But nevertheless, if you have the business’ best interests at heart, you ought to try to fix the problem and not paper over it with code.

We programmers talk about getting rid of accidental complexity so that our code contains only essential complexity. And business processes are what we think of as essential complexity. Fair enough. But business processes have accidental complexity as well. Business processes suffer from poor maintenance over time. Business processes need to be refactored as well, and when you have a project to automate a process, you have a certain amount of freedom to challenge the process, to prod and poke it, to question it. Don’t assume that you have to take it as entirely given, a set of requirements cast in stone.

Remember, always, that our job is to add value, not just to cut code. And like so many other places in software, sometimes our best code is the code we didn’t write. Identifying a broken process that leads to simpler software could be be best value you can contribute to a project.

---

1. Writing 7,500 lines of anything instead of 50,000 lines of something else is still useful, if for no other reason than with 50,000 lines of something, it is hard to know whether there are 50,000 lines because the business process is unnecessarily gnarly or whether there are 50,000 lines because the programming language is full of accidental complexity. But if you have another language that could express the same thing in 7,500 lines, gnarliness in the business process is readily apparent.
   
   [back]


2. There could be another entirely different reason why a piece of software that is “gnarly and contradictory and full of exceptions and holes, and is impossible to understand” may be a sign that the business has problems: Conway’s Law.
   
   [back]

  ¶ 5:00 AM