Adaptive Path Blog

Lately, it’s become fashionable to dismiss documentation as an impediment to product development. Get rid of all that useless stuff, we’re told. You don’t need it–it just wastes time. If you need documentation, you are doing something wrong. Go straight to making the product. Just build it.

Although I’m risking once again being crowned a king of documentation, I say: nonsense.

While I think the methodology of “minimal documentation, rapid development” might work some of the time for small teams working closely, I’d never recommend it for all teams at all times. That’s asking for a return to the crappy, poorly-thought out products of the 1980s and early 1990s. Haven’t we been down this path before?

Small teams can do small things well. A small crew can build a house, but it takes an army to build Notre Dame. For large projects, you usually need large teams. You can’t build Yahoo, Amazon, or Apple’s OS X with a handful of people. There are too many moving parts to be managed. Something needs to bind those large teams together, and that something is often documentation. Something that says, this is what we’re building and why. Blueprints. Things that remind team members of decisions made, instruct how all the pieces fit together, and, yes, even inspire. Oh right, this is what it’s supposed to look like and how it’s supposed to act.

For complicated applications with many constraints, states, and business/design/technical rules, I can’t imagine doing the design in any other way. Actually, I can–and have–and it’s been a disaster. Essential tasks have gotten overlooked, code has had to be rewritten, users have been angry and unhappy. So, really, I can’t imagine wanting to do it any other way for the type of projects I usually tackle: ones with those many constraints, states, and business/design/technical rules. The challenging interesting projects.

Here’s my dirty little secret: I do most of my designing while documenting. Sure, I sketch and use a whiteboard. I doodle design ideas on scraps of loose paper lying around on my desk. I dream up designs while walking to work. Those tools and tasks are essential for concepting. But the meat-and-potatoes, nuanced, well-thought out designing I do is done while I’m doing documentation–task flows, wireframes, prototypes. The documentation makes me think through the design in a careful way. I can sketch all sorts of unbuildable, illogical designs all day on whiteboards, but until I take the time to really write them down in a logical way that communicates the design–and my thinking–clearly, the design is half-baked. Indeed, the documentation crystalizes my thinking, making me think through all the issues and present the solution to them in a way that makes sense–to me and to those who are paying for and building the design.

I am not suggesting documentation be done because it should be. It should be done because it needs to be–either to create the design itself, or else to communicate the design to others. If the documentation does neither of these things, it’s useless. Less than useless in that it wastes everyone’s time. And time, as Ben Franklin reminded us, is what life is made of.

This entry was posted on Monday, May 22nd, 2006 at 12:07 pm and is filed under Idealism, uncensored, Information Architecture, Interaction Design, Product Design, Web Applications. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.

This post is licensed under a Attribution-Noncommercial-No Derivative Works 3.0 Unported License.