Use cases, functional specs, interface specs, site maps, you name it. I have yet to come across any of these documents that are usable. I’m as guilty of this as the next person, but if our job as information architects, interaction designers, or whatever we call ourselves, is to help create interfaces for humans, then why do we use tools and create documents that are mind-numbingly unusable by the engineers and programmers who are supposed to build it all.

I’ve worked with a lot of clients, and I’ve seen a lot of documentation. Over the last couple of years, I’ve done my best to migrate away from traditional documentation methods and find ways that actual help others visualize what the end product should look like. I’m a huge proponent of rapid prototyping whenever it’s feasible, and I strongly believe the value of functional specs and use cases as they are used today serve a very limited role.

The Problems

  • Document Debt – These documents are almost never designed to have any real life expectancy.
  • Unusable – These documents are virtually impossible to translate into screens and a user interface. They do very little to take the end user of the document, engineers, into account.
  • Separation Anxiety – There’s almost always a plethora of documents that are all inter-related and do a fantastic job of separating the information so that you have to swim through multiple documents just to find the details on one simple thing.
  • Not Engaging – There is nothing about these documents that makes them interesting. It becomes extremely tedious for people to create them and to read them. This leads to confusion and apathy towards the quality of these documents. Let’s just be honest. Nobody likes to write them, and nobody likes to read them. They don’t engage their users.
  • Unnatural – Creating multiple disparate documents is not a way to organize information.
  • Illusion of Agreement – As the good folks at 37signals have noted, these documents only create the illusion of agreement. Words leave room for interpretation, and that leads to assumptions and miscommunication.

The Solution

I don’t have the details worked out yet, but I’m slowly putting together a vision of how we can really document web applications in a pragmatic way. The primary driver is to create something that people can understand, and to make documents that engineers actually look forward to using. It’s a hybrid of wireframes, page description diagrams, and functional specs.

it’s about designing modules, bits, and building blocks. Those modules are then heavily and appropriately documented based on their usage, behavior, limitations, etc. The modules would each fit on their own single piece of paper. If a module starts to require more information such that it won’t fit on a single sheet of paper, it needs to be broken out into smaller modules.

Of course, documenting modules is only good if there’s a clear higher level vision, but for the sake of focus, we’ll assume that’s already happening. The problem lies with how we’re expressing that vision on paper. I’ve been hashing it out recently, and it’s coming together nicely. As with anything, I don’t think it’s the solution for everything, but in the right circumstances, I see an incredible amount of potential.

As a quick disclaimer, the catch here is that use cases and functional specs are traditionally used to create the requirements for the app. Those requirements then evolve into wireframes based on a traditional waterfall approach. A lot of my ideas are based on my belief that requirements should not be developed independent of the user experience. The requirements and interface should be developed hand in hand. So, if you disagree with me there, this approach might not be right for you.

Summary

We can’t escape the need for documentation. Pictures aren’t detailed enough, but words aren’t clear enough. Engineers sit down and program modules. They should be able to sit down with one sheet of paper, maybe front and back, and code a module without interruptions. They shouldn’t have to swim through half a dozen documents, go back and forth asking questions about details that were overlooked.

If we’re so concerned about interfaces and humans, it’s time we start giving the interface to our documentation the innovation and atttention that we give to the rest of our interfaces. I hate talking about things before they’re finished, but I couldn’t contain my excitement/frustration anymore.