In Defense of Documentation

At recent conferences and in discussion groups, I’ve found it’s become increasingly popular to deride design documentation as time-wasting, inscrutable, and pedantic.  There’s a growing drive to jump directly into development, and manage design on the fly.  Few people are providing cogent arguments to the contrary.  As an IA who prides himself on the quality his documents, I feel the need to address the role of the spec in the age of Agile.

Bad documentation is real, and must die

There’s no doubt that there are some absolutely terrible documentation practices out there.  If you’re writing several dozen pages of design strategy in plain prose, you shouldn’t be surprised when no one bothers to read it.  A core measure of a development effort’s success is its efficiency, and documents that slow down the process should be hastily ditched.  It makes no sense to compound the time lost in writing poor documentation with even more time spent reading it.

Good documentation is also real

Good documents are completed quickly, express ideas efficiently, expedite development, build trust among team members, and allow people to achieve things that would otherwise be impossible.  People enjoy reading and discussing them, and teams of designers, developers, writers, and clients work as a whole to review and iterate them.

An analogy

Two years ago my wife and I decided to upgrade to an HDTV.  The problem was that we were going from a 24” tube set to a 46” flat panel, and the new set wouldn’t fit our existing furniture.  Even worse, the money we were spending on the TV precluded us from buying new stuff.  So I decided that I’d build a TV stand myself.

"Wireframe" of our TV stand

"Wireframe" of our TV stand

Now you need to understand that I’m not the sort of person you might describe as “handy”.  I’d never built so much as a birdhouse, and my high school didn’t even have a wood shop.  I had absolutely no idea how to construct a physical object.  Furthermore, my wife strictly forbade the use of any saws or sharp objects for fear I might cut off something important.

So I decided to create a physical object in the same way I would create any virtual one: I drew up a wireframe in Visio.  Before picking up a hammer or even buying the wood, I first mapped out the whole vision on paper.  I shared early top-level designs with my wife, we talked them through, and I modified the plans until we agreed on the approach, and then I filled in all the low-level details.

The completed TV stand

The completed TV stand

I’m pretty pleased with the result (see the picture at right).  It’s not exactly Herman Miller, and it weighs about 50,000 pounds, but it meets our needs precisely and cost me just under $100 to make.  And this example illustrates a few key advantages to a good documentation process over going straight to development:

  • Faster completion time. The documentation itself only took two days to develop, and since everything was planned out beforehand there was no wasted development time.  I got the project done in six weeks, much faster than I could have without the documentation.
  • Control of design. There’s a terrific symmetry between the design on paper and the finished product.  This was very important, because a lot of factors had to be balanced in the design: ensuring structural integrity, fitting all of the components in without making the stand too tall, and creating aesthetic beauty.  Jumping straight in, I wouldn’t have been able to manage that balance.
  • Planning around restrictions. It’s hard to build something out of wood when you can’t use a saw.  Lowe’s could cut the wood for me, but they could only do straight cuts at 90° angles to the board.  This was a built-in hardware limitation – not a deal-killer, but it required some creative planning.  Accounting for restrictions in the documentation keeps them from becoming show-stoppers later on.
  • Lower risk. Of course I could have jumped straight into the build, but that would have been much more risky.  I would have wasted a lot of lumber.  It could have come out looking terrible.  I could have discovered halfway through that there was a much better way of doing it.  Designing it on paper first was harmless, and maximized my chances of success later on.

Hmm, now what could that have to do with UI design?

By now this connection should be abundantly obvious.  In fact, from the most general point of view of process there is no useful distinction between building a TV stand and building a website.  Both require design and development efforts.  Both involve costs and risks.  Both produce an end product that needs to satisfy many needs equitably.

Quality documentation allows people to achieve things that are otherwise impossible.  The human brain can only do so much on its own – we need to extend its capabilities by processing things on paper, with our hands, and through conversation.  The task of designing software is often so complex that you can’t even grasp the full problem until you’ve written enough of it down.

But perhaps most critically, a good document provides for a foundation of trust to be built between team members.  Developers shouldn’t have to do design – it’s a distraction from their responsibilities, and exposes them to accountability for decisions that should have been handled by someone who’s paid to make them.  If the developers can trust that all foreseeable design decisions have been anticipated and built into the documentation, they’ll stick to it zealously.

What about Agile?

“Agile” is the name given to a process of rapid iterative prototyping and efficient communication.  I think it’s a terrific thing, because it allows concepts to be tried out and massaged into good shape in short order.  I employed a bit of Agile while building my TV stand – using scrap wood to figure out to make dowel joints and apply a stain, and grabbing whatever was within reach to get a job done.

But Agile has spawned a certain animosity toward even very high quality, efficiently produced, time-saving documentation.  I don’t think that’s Agile’s intention.  I think it rightfully seeks to eliminate time wasted producing documents that no one will bother reading, but perhaps its mantra has been repeated so often that it’s grown beyond its original meaning.  Played out to its logical extreme, ditching documentation would lead to disaster on all but the simplest projects.

So what should we do?

We need to reestablish the role of documentation in the product development lifecycle.  To do that, we first need to come to grips with the fact that what people have received in the past has been found wanting.  So we need to make a few key changes:

  • Crank it out. We need to be able to turn documents around faster than developers can build to them, or else we’ll become a bottleneck.  Our documents should be done in the simplest form possible, with no excess ornamentation or verbosity.  Ugly is efficient.
  • Communicate efficiently. We do after all work in usability, so our top priority should be to keep the needs of the document’s consumers in mind.  Integrate images with text effectively, speak clearly, and edit out anything that doesn’t solve a problem.
  • Know your medium. We don’t need to be coders, but if we understand how HTML, CSS, scripting, and databases work we’ll be able to take advantage of the strengths of these technologies.  Marshall McLuhan was right – the medium is the message.
  • Make people’s jobs easier. Bad documentation adds to other people’s workloads.  Good documentation lightens them.  Everyone will be happy to have something that reduces the total number of decisions they need to make.  Our documents should take control of everything that will affect the usability of the system.
  • Produce gold. People need to believe you’ll design something that will make everyone involved look good, and bring them to a better outcome than they could hope for without us there.  Get everyone’s input into the document as it’s developed, and iterate it repeatedly to build confidence in the finished product.

5 comments so far

  1. Richard on

    You’re such a geek 😉

    By the way, your TIVO box is 1/2 inch out of alignment.

  2. Kishore Kumar on

    Agile Methodists are Real Programmers (who don’t eat quiche) grown old 🙂

    “Real Programmers don’t write specs. Users should be grateful for whatever they get: They are lucky to get any programs at all.

    Real Programmers don’t document. Documentation is for simpletons who can’t read listings or the object code from the dump.

    Real Programmers don’t comment their code. If it was hard to write, it should be hard to understand and harder to modify.”

    Agile Methodists deny not just design documentation but also project management in favor of “working software”. Check out my blog post on this topic:

  3. kaa on

    i love the way you explained your point 🙂

  4. Scott on

    I want, nay, NEED plans for this awesome TV stand, did you keep any documentation? I think most of the information could be collected from the dimensioning, but what material did you go with? 2″ x something, and the thinner shelves are 1″ x something? What’s holding it together?

    Thanks for posting this, even if it was a year ago.

  5. Rohan on

    The TV stand design and final outcome is awesome. Love that it cost you less than 100, plus some devoted time. You should be proud of it.

    Any other documentation on the design would be most appreciated.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: