(This is a snapshot of my old weblog. New posts and selected republished essays can be found at raganwald.com.)

Monday, March 24, 2008
  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.1

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.2

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.


  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.


Comments on “Is software the documentation of business process mistakes?:
Slightly OT question: was it intentional to link to the 1990 edition of The Design of Everyday Things? Is it preferred over the 2002 edition?
>>Could software be a list of business process mistakes?

Yes. I have long felt that business software is the crystallization of business practices, including all their warts and contradictory actions. Yes, it is part of our job to tell them where their business processes have run amok. I think this is why someone seasoned in this sort of software is often running their own company -- they have practice fixing broken business processes.
Thanks for the catch, Vineet!

Actually, the older edition is the one on my shelf, but if I were shopping for a copy today I would buy the newest one.

Either way, one of the favourites on my shelf. If I ever re-do my favourite books list, I think this one may wind up in the top ten.

Interesting insight, thanks!
One option is to use (or build) a rules engine, such that your business rules are softcoded relative to the rest of your application. Then it's easier to look at the business logic separate from the rest of the software and identify any business process problems separately.

The current system I and my team has built doesn't make this as easy as I would like yet, but we do have that fundamental separation encoded. As the software developers, we spend almost no time writing business processes and CRUD forms -- we simply build a system in which business processes can be represented. We then have a team of semi-technical project management folks who have better domain understanding and are responsible for working with end users to capture the actual business processes and represent them using our system.

It's a fairly effective system, it makes for happy programmers (since our team spends our time building actual features, not just the same old CRUD forms and business rules), and it makes for happy end users (since the people who work most closely with them are the ones actually building out their system).
One option is to use (or build) a rules engine, such that your business rules are softcoded relative to the rest of your application.

The Separation of Concerns Holy Grail :-)

Sometimes it is done reasonably well (see the DSL describing proof of eligibility), and sometimes not so well. But when it goes well, it is beautiful!
Business processes are full of accidental complexity, that's well known, widely researched, and addressed by Business Process Reengineering.


Part of the decree is identifying those parts of the process that add no value. Instead of automating them (with or without software), think first how to eliminate them.

BPR was widespread in Fortune 500 companies years before Martin Fowler's Refactoring hit the shelf, and in my experience is years ahead of the equivalent software development practices. Not just in modeling and analysis, but also in paying more attention to the human factor.

Business processes are full of accidental complexity, that's well known, widely researched, and addressed by Business Process Reengineering.

True that!

But nevertheless, isn’t it amazing how many times you still hear the phrase, “That’s the way we do things around here”?

Thanks for the link!
Nice post, Reg.

It makes sense that software would conform to the business requirement, just as it conforms to the hardware on which it runs. Software is the most flexible of the three.
Another excellent essay. Kudos for putting up.

This might be a little off topic, but it reminded me of something that I've seen my current company struggle to understand for years:

When your software is non-intuitive the documentation for that software becomes a second user interface. (It's a second UI because it begins to dominate the way customers interact with the software.)

If that second user interface stinks or is lacking then you're in a world of hurt.

Who was it who said that all technology problems are social problems - and all social problems are technology problems?
leoc: Not sure if this is what you meant, but DeMarco and Lister asserted in Peopleware that technology cannot be used to solve people problems, and that 90% of the problems in the technology industry were people problems.


But it may also be a sign that the underlying business process is gnarly and contradictory and full of exceptions and holes.

This happens so often in my contracting that I stopped considering it a special case. I now have several speeches prepared on the topic for my clients, the shortest one of which goes, "The first thing we will discover as we try to teach a computer to do your job is that you do not, in fact, know how to do your job."

<< Home
Reg Braithwaite

Recent Writing
Homoiconic Technical Writing / raganwald.posterous.com

What I‘ve Learned From Failure / Kestrels, Quirky Birds, and Hopeless Egocentricity

rewrite_rails / andand / unfold.rb / string_to_proc.rb / dsl_and_let.rb / comprehension.rb / lazy_lists.rb

IS-STRICTLY-EQUIVALENT-TO-A / Spaghetti-Western Coding / Golf is a good program spoiled / Programming conventions as signals / Not all functions should be object methods

The Not So Big Software Design / Writing programs for people to read / Why Why Functional Programming Matters Matters / But Y would I want to do a thing like this?

The single most important thing you must do to improve your programming career / The Naïve Approach to Hiring People / No Disrespect / Take control of your interview / Three tips for getting a job through a recruiter / My favourite interview question

Exception Handling in Software Development / What if powerful languages and idioms only work for small teams? / Bricks / Which theory fits the evidence? / Still failing, still learning / What I’ve learned from failure

The unary ampersand in Ruby / (1..100).inject(&:+) / The challenge of teaching yourself a programming language / The significance of the meta-circular interpreter / Block-Structured Javascript / Haskell, Ruby and Infinity / Closures and Higher-Order Functions

Why Apple is more expensive than Amazon / Why we are the biggest obstacles to our own growth / Is software the documentation of business process mistakes? / We have lost control of the apparatus / What I’ve Learned From Sales I, II, III

The Narcissism of Small Code Differences / Billy Martin’s Technique for Managing his Manager / Three stories about The Tao / Programming Language Stories / Why You Need a Degree to Work For BigCo

06/04 / 07/04 / 08/04 / 09/04 / 10/04 / 11/04 / 12/04 / 01/05 / 02/05 / 03/05 / 04/05 / 06/05 / 07/05 / 08/05 / 09/05 / 10/05 / 11/05 / 01/06 / 02/06 / 03/06 / 04/06 / 05/06 / 06/06 / 07/06 / 08/06 / 09/06 / 10/06 / 11/06 / 12/06 / 01/07 / 02/07 / 03/07 / 04/07 / 05/07 / 06/07 / 07/07 / 08/07 / 09/07 / 10/07 / 11/07 / 12/07 / 01/08 / 02/08 / 03/08 / 04/08 / 05/08 / 06/08 / 07/08 /