Effective Design Documentation Without a Fuss: An Interview With Dan Brown

UX Lisbon

Three day conference happening in the lovely Lisbon Portugal. The 2012 event will take place from 16 to 18 May.

See all posts

This May, Dan Brown will be speaking at UXLX in Lisbon, Portugal. As part of our media partnership with UXLX, Johnny Holland got the chance to interview Dan on a topic that he has been the go to expert for years now, Effective Design Documentation. We’d like to thank Dan once again for taking the time out of busy schedule for this interview. Hope you enjoy.

JohnnyHolland: Given all its moving parts, design can be a challenging thing to document properly. What advice would you give to design teams that are attempting to get proper Design Documentation injected into their organizations process?

Dan Brown

Dan Brown

Dan Brown: “Design documentation” is shorthand for the collection of techniques to capture and communicate design ideas to other people on the design team. Those ideas may be half-baked or they may be well-cooked, and designers have various reasons for creating documentation. “Documentation” may not be a printed PDF: it can come in many forms, including interactive prototypes. Regardless, documents are any tool that communicates a design idea and ensures projects run smoothly.

Let’s now unpack “proper design documentation”. Different organizations face different challenges, and documentation that works for one group may not be “proper” for another.

The central challenge we see time and again is ensuring consistency: different designers communicate the same concepts differently. Consistency remains important, since different designers may be working with the same stakeholders, developers, and quality engineers. Imagine being on the receiving end of those deliverables, not knowing what to expect from one project to the next. One designer provides painstaking detail of every interaction and the other leaves more to interpretation.

There are lots of things a team can do to normalize their deliverables, but using templates is not one of them. Ultimately, the content of the documentation must be driven by the project itself: forcing people to fill in the blanks yields unreadable deliverables. Instead, to ensure consistency, the design team should meet regularly — monthly or quarterly — and share their work, examining their deliverables as a single portfolio. They should identify opportunities to streamline and align so that readers of their documents aren’t bombarded with a new approach in every project.

How has EightShapes Unify helped design teams create and manage the documentation they create?

Early in EightShapes’ history, we established ourselves as a firm that didn’t just do design, but also helped design teams communicate better. This can mean a few different things:

  • translating mature design systems into re-usable components to speed up the design process and ensure consistency in the resulting designs
  • preparing guidelines around the use of design systems
  • running workshops to help teams correct the discrepancies in their approach to documentation

When Nathan conceived and implemented EightShapes Unify, however, we had a real opportunity to make a broader impact. Through much soul-searching (and expensive lawyer meetings) we decided to release it for free. We can’t know how everyone uses it: it’s been downloaded more than 15,000 times, by teams of multitudes and teams of one.

Everyone at EightShapes has a different perspective on the value and impact of the documentation system. For me, the beauty of EightShapes Unify is the freedom from meaningless templates. I remember using meaningless templates earlier in my career, answering questions like “Who are the actors of the system?” and “What are the dependencies?” These questions are either so broad or so irrelevant that the document becomes a mish-mash of trite responses.

Instead, the system provides “page patterns” — simple page layouts used frequently for common tasks like explaining a wireframe or comparing two approaches. This task-based approach to documentation mirrors our design philosophy

How has UX documentation had to evolve over the past few years? Did this have any influence on why you wrote a new edition to Communication Design?

There are two factors exerting pressure on documentation–the design problems and the project participants. My experience shows a marked increase in both over the last several years.

People generally point to new interface conventions (carousels, accordions, fly-outs, mega-menus, ad nauseum) as driving the evolution of documentation. But web sites went from nice-to-have to essential business tool overnight. The range of new UI patterns is only a small fraction of the story: more companies are trying to do more work online. This means increased complexity in transactions and depth of information. These sit at the heart of new design problems, and they force us to reconsider the tools we use to describe our solutions.

At the same time, there are more people involved in the web design process. Our projects incorporate team members with a greater range of experience and broader perspectives. They have different interests in the project and different agendas for the outcome. All of this puts pressure on the design documentation, serving more needs and purposes.

I wrote a new edition of Communicating Design to scratch an itch—much of my thinking around documentation had evolved over the preceding five years. These two pressures—new challenges, new participants—contributed substantially to the changes in my thinking.

Considering the current trends towards mobile, tablet, and in general ubiquitous design, how will UX documentation have to evolve yet again to support these new challenges?

At EightShapes, we’re exploring how interactive prototypes cooperate with other kinds of deliverables to document the entire user experience. Coming from a passion for good communications, we acknowledge that increased complexity demands a multi-pronged approach for defining experience.

Luke Wroblewski’s “mobile first” design approach resonates strongly with me: in a recent project, while I was sketching concepts, I started with the tablet version of the application without even really thinking about it. If the trend continues, however, we designers will need to separate further from specific platforms and start with the underlying models.

The biggest challenge for designers will be the increasing emphasis on abstraction. As data becomes available everywhere, the models we use to define its structure across multiple platforms must divorce themselves from any one specific platform. If the available information and its inherent structure is one factor driving the design of an interface, we need better tools for designing those structures. In short, the more abstract side of information architecture receives greater emphasis.

Why is creating good documentation essential to a designer, regardless of what their current role is?

We are purveyors of stories. We design products to support the stories of users’ lives. We design products that presumably bring about a change, going from “Eli suffers from situation X” to “Eli benefits from product Y”. This is how we do design and how we describe our ideas to other people involved with the product.

A design document tells a little story in and of itself: for example about how a particular feature works, or the conclusions stemming from user research. A document a also contributes to the overall narrative of the project. But the most important story is the one about the product, how it works to bring about change. This multi-layered approach to storytelling is the essence of designing an interactive product.

User experience designers must be able to create good deliverables because they should be able to tell a good story.

What are the dangers of going from the whiteboard to design/development?

There may be none, but that’s not true for every case. Planning is crucial to both design and development: knowing what you’re going to do before you do it can prevent wasted effort and unnecessary detours. Experienced designers know how much planning and design they need to do based on the nature of the problem, the existence of well-established patterns, and the composition of the team.

That said, no amount of planning can ever replace the brute force method of trying lots of different things. Discarded ideas might not be a sign of wasted effort, but a necessary by-product of the creative process. One might argue that successful creative endeavors depend on the balance between planning and trying things out.

Some signs that you might need more robust documentation include:

  • Working with new team members, where communication conventions have not yet been established
  • Working on a project with multiple streams of work, where keeping track of progress on each stream is crucial
  • Working on a project with clear milestones, where the project team expects each phase to come to a solid conclusion
  • Working on a poorly-defined design problem, where taking the time to define boundaries is time well spent

I’d recommend creating more documentation in new situations just because it forces you to communicate clearly and acknowledge constraints. If you start creating documents for the sake of demonstrating productivity (rather than moving the project forward), perhaps its time to go back to the whiteboard.

How can designers move beyond being all about the documentation? How can they stop being deliverable monkeys?

As I thought about this question, I really wanted to understand what “all about the documentation” and “deliverable monkey” means. (And if you think it’s easy to get past the picture of a thousand monkeys sitting down at a thousand MacBooks, you are wrong.) I came up with two things:

First, designers in our field can often feel removed from the product. We’re pushing boxes around a page, composing annotations that no one reads. We’re writing mark-up and code strictly for the purpose of demonstrating an interaction, but know full well it will be tossed when it comes time to build the product. Our involvement ends once we’ve told the story, capturing the experience sufficiently for someone else to build it.

We feel like we’re paid to create things that are at once essential to defining the product and are still so far away. This demand to churn out wireframes all day long makes us feel like, well, monkeys. (No disrespect to our primate cousins. I’m sure they lead very productive, fulfilling lives.)

Second, in order to feel connected to something, designers sometimes focus more on the deliverable and less on the product. We pour our ego into the PDF, reflecting our passion for the product in the documentation, something we control.

Both of these things come from designers themselves. That is, if you think treating these issues depends on a systemic intervention, you’ve looked too far for a cause.

Here are some things that have become ingrained in my work, that help prevent any possible devolution:

  • Determine the barest minimum that needs to go into the document in order to communicate the ideas effectively. Try not to do much more than the barest minimum, but definitely don’t do less. Can the team sufficiently understand your intent with some rough wireframes and light annotations? Perhaps embellish those with some context through business objectives and user requirements, but avoid doing much more.
  • Treat the document as a framework for a conversation, not as a final product. By thinking of it as a means to an end, rather than as an end in and of itself, you approach it differently.

How could proper UX documentation have prevented the Cylon Uprising?

Products sometimes behave in unexpected ways. Some ways are delightful, like when you discover that shaking your iPhone “un-does” your last action. Some are disturbing, like when robot servants rebel against human oppression. While good documentation should capture all the functionality of a product, we can’t predict how people will use it, and people always find new ways to use (or abuse) products.

UX Lisbon 2011

Dan Brown will be  speaking at UX Lx: User Experience Lisbon, one of Europe’s premier user experience events. The second annual UX LX conference takes place May 11-13, 2011 in Lisbon, Portugal.

Brad Nunnally

Brad Nunnally is a User Experience Design Consultant at Perficient based in St. Louis, MO. Aside from writing, plotting UX world domination, and tweeting a whole bunch , he fills his time playing with his son and dog.

2 comments on this article

  1. Pingback: Designad för att hackas | Emilia Blom

  2. Pingback: What I Have Gained from the Virtual Team Assignment « el6082katrina