Six Tips for Improving Your Design Documentation

Written by: Ryan Olshavsky
“Writing effective design documentation (like design itself) is really all about making sure you serve the needs of your audience.”If you are a designer or product planner, you probably create documents of some kind to capture your design decisions and solutions. Documentation is a crucial component of successful product planning and implementation, so it’s important that it communicates as effectively as possible. Good organization, complete information, and clear writing are, of course, key to the success of any design document, but there are some other, less-obvious techniques you can use to make your documents more readable and understandable. Here are a few of them.

(Note: I refer to “the document” throughout this article, which implies a bound stack of paper, but a printed volume is just one—and not always the best—way to present design documentation and specifications, as Brian Krause points out in his article, “Getting Creative With Specs: Usable Software Specifications.” While many of the following tips are described in the context of printed documents, most of them can be applied to design documentation in any format.)

1. Know your audience
Writing effective design documentation (like design itself) is really all about making sure you serve the needs of your audience. So before you begin writing, it’s worth finding out who your audience is and what, exactly, it needs.

Most important is to know who your primary audience is. Is it programmers, project managers, executives, designers, marketing people? It can be difficult to satisfy every reader in a single document, so, if possible, pick just one target group of people and write for them. If you must serve everyone in a single document, organize it so that each audience can read just the section that applies to them, and not be bothered with the other stuff.

Next, ask yourself—or, better yet, ask your readers—what they want to get out of your document. What will satisfy their goals? Do they need something to help them make a decision? Do they want to better understand who the users are? Do they need to know exactly how the interface behaves and looks? The answers to questions like these should inform the structure, tone, and emphasis of your documentation.

Also important is the culture of your audience. You must be aware of the ways in which your audience uses documentation, and when. What language does your audience speak—technical, marketing, design? What other kinds of documents do they use, and how? Does a paper document make sense, or would a presentation be more appropriate? You want your document to integrate into your audience’s culture, not disrupt it (unless, of course, the intent of your document is to shake things up).

Once you know who your audience is and what they need, you’re ready to start writing. As you go, regularly double-check yourself to make sure you are still on track to deliver your audience what they need.

2. Tell a story
A major goal of design documentation, especially in the early stages of a project, is to educate its readers about the value of the design itself (rather than the specifics of it), and convince them that the product is worth building and producing. One effective way to help people learn and understand these concepts is to present them as narratives: Instead of thinking of your document as simply a well-organized collection of specifications, descriptions, illustrations, and diagrams, try telling a story. Your design document doesn’t have to read like a novel, but incorporating some novel-like elements into your work can often be surprisingly valuable.

Using characters
All novels have a main character, and your design document should, too. If you used personas during the design process, you’re set. Since personas represent the goals and needs of the people who use the design, they are a natural choice for the main characters of your documentation. They even have names, backgrounds, preferences, ambitions, and goals, just like people in a book. Throughout your document, refer to your personas by name, and refer to them often. If you are describing how a product might fit into a market, write a story about how Alison benefits from using the product in her life. If you’re explaining a complex behavior of the product interface, cast it in terms of Daniel’s actions and reactions.

Even if you don’t use personas, per se, it’s a good idea to have some representation of the user in your documentation (more than just bland, generic “the user”). Something as simple as a sketchy description or outline of the target user’s characteristics, coupled with a name, can be quite compelling.

Using scenes
Two excellent ways of presenting the narrative of the design are scenarios and walk-throughs.

Scenarios are like short stories: they communicate a persona’s situation, and describe her motivations, expectations, and goals, without getting into the details of the design. Scenarios are especially useful in the early stages of a project, when conveying the value and purpose of the product is key. Here’s an example passage from a scenario:

Jane’s brother’s birthday is coming up soon and, after much consideration, she has decided to buy him the Ansel Adams retrospective book he keeps talking about. It’s not cheap, though, and she’d like to find the best price. She decides to check because she’s had good luck with the site before, so she opens her browser and types in the URL. When the page loads, she’s pleasantly surprised to find that it remembers who she is and has even stored the items she was thinking about purchasing the last time she visited the site. Jane clicks in the “ShopAround for:” field and types “ansel adams”…

Notice that this scenario doesn’t specify what the ShopAround site looks like, or what content is featured on the home page. Instead, it focuses on what’s important to Jane: that it remembers her and what she was shopping for last time. It also only describes Jane’s interactions with the page that are pertinent to her goals—namely, finding the book she wants to buy.

Walk-throughs, on the other hand, are good lower-level communication tools. They are basically step-by-step procedures that explain how the persona does something with the product, each action she takes, and each response she gets from the system. Walk-throughs are great for explaining interface behaviors. Both scenarios and walk-throughs work best when accompanied by illustrations or screenshots of the design. The text part of a walk-through might look something like this:

      1. Jane types URL into browser Address field and presses Enter

      2. Display ShopAround homepage
      3. Display user name in the Sign In module
      4. Display user’s most recent items in Shopping Cart module

      5. Jane types “ansel adams” in ShopAround field

      6. Query for search string
      7. Load page with search results

Be careful when using a narrative-based document structure, though. It’s not appropriate in all situations. For example, some design documents are used as reference guides for developers; those documents must present information clearly and concisely, and in a way that makes it easy for programmers to find what they need. Here, story-telling might get in the way. One approach is to use narrative to provide an overview of each element of the design, then use a more straight-forward format, like bullets or numbered lists, to convey the nitty-gritty details of each element. Again, always be aware of the needs of your audience, and structure your document so it best meets those needs.

3. Describe the rationale and implications of the design
When you’re documenting a design, it can be tempting to just explain how the product works and show what it looks like. But for many in your audience, that’s not enough. They also want to know the “why?” behind the design. They may wonder why a particular feature was (or was not) included, or why a certain interface element looks or behaves the way it does. While you don’t want to overload your document with too much exposition, providing a bit of rationale where appropriate is another way to get your audience to embrace the design.

The best way to support a design decision or solution is to frame it in terms of how it serves the needs of your users (here again, personas are useful if you have them). Explain how each decision will help your users satisfy their goals and how it will make their experience more powerful or pleasant. Most of the time, using this approach will answer your audience’s “why?” questions even before they ask them.

While providing rationale for your decisions answers your audience’s questions, it can also be a great way of showing that you’ve considered the needs of your development organization. Describing the design in terms of the business requirements it satisfies can help put the minds of product managers and executives at ease. Similarly, using design principles to back up unusual or unique interface behaviors can reassure programmers that what they code is sensible. There’s a benefit for you, too: providing reasonable arguments for design decisions gives you authority. It demonstrates that you know what you’re talking about, which means fewer “well, I think it should be this way” discussions with developers.

Additionally, it can often be valuable to include discussions of the implications of the design. If the design requires certain changes or additions to the technical architecture of the product—such as the need for additional server-side functionality or streaming Internet connectivity—address them up front, so engineers can make fully-informed decisions about how to implement the design.

4. Stick to a grid
Something that is often overlooked is the design of the document itself. Chances are, you’ve come across few examples of development documents that, while full of excellent content, are almost impossible to read because of their haphazard layout. Making the format of your document visually clear and consistent from page to page is just as important as getting the content right.

Effective documents rely on a fixed grid of page elements. Flip through the pages of any book on your bookshelf, or any above-average news website—notice how the bodies of text all line up, and that the header, footer, and margins are the same on each page. That’s the grid. It’s not there only for aesthetic reasons. Having a clean, organized layout means your readers don’t need to do as much work to find things on the page or to make sense of the content they see. A grid also lets you focus on what you’re writing, instead of trying to figure out where to put things on the page.

Applications like Adobe FrameMaker, InDesign, or QuarkXPress make it fairly easy to establish a consistent page layout grid, and many of them offer sample templates to get you started.

Document Grid
Well-planned page layout grids maintain “white space” in the margins and between page elements. This lets your pages “breathe.” Don’t cram things together just for the sake of getting them all on one page.

5. Use the present tense, active voice
If you are producing design documentation, the product is what you write, and the tone of your writing should reflect that. Compare these two sentences:

   The user is provided with a screen for entering data.


   The user enters data in a screen.

The first sentence is written in passive voice. It’s wordy, and somewhat awkward. The second sentence is in active voice. It is strong, definite, and clear. Using active voice makes your writing bolder, more direct, and more concise. In your documentation, write as though the product already exists, and you are simply explaining it to a colleague (“the product does this…,” as opposed to “the product would do this…”). When you write with conviction, your confidence and belief in the design is carried through to the reader, and helps make the design more persuasive to your audience.

6. Get a partner
No major book or article is published without an editor. Your design documentation should be no different. Find somebody who can review drafts of your document periodically, before you hand it off to the developers. Ideally, your editor should be a teammate—someone who is already familiar with the design and the project—but a colleague or a trusted member of the development team will work, too.

You and your editor should ask: Is the design described correctly? Will the developers “get” it? Is the organization clear? Are all the key points covered? Have the important technical and development implications been addressed? And so on. Check in with your editor regularly, not just at the end before your document goes to the printer or the web. It’s much easier to deal with holes in your content or problems with your organization scheme if you catch them in early drafts.

As you go through the editing process, keep in mind your ultimate goal: to get the best design produced and out the door. Don’t get too attached to your prose—no word, sentence, or paragraph is precious, and if reworking what you’ve written serves the greater good, do it.

These tips are just a few of the things that go into crafting a great design document (there are many more), but following any one or all of them will help you better serve the needs of your audience. And if your audience of developers and business people is happy, it’s a good bet the users of your product will be happy too. Write on!

Ryan Olshavsky has over five years of experience in interaction design and design documentation. He is currently an Interaction Designer at Yahoo! Inc., a small Internet company. Previously, he worked as a design consultant at Cooper.

Information Architecture: Blueprints for the Web

Written by: Ryan Olshavsky
“A guru, in Wodtke’s terms, is nothing more than a critic who prescribes rigid, oversimplified “rules” of website design.”Recently, a website designer friend asked me, “If you had to recommend one book for a non-designer to understand our design process, what would it be?” I thought for a few moments. Then for a few more. And a few more. Strangely, I couldn’t come up with one. While there are many fine books that go into great depth on various aspects of the information architecture and design process, I was unable to think of a single one that provides a concise, 10,000-foot view of what we do. However, if my friend were to ask me this question again today, I would quickly refer her to “Information Architecture: Blueprints for the Web”, Christina Wodtke’s new book targeted at people new to the field.

Formerly a partner at Carbon IQ, a user-experience firm in San Francisco, Christina now leads the user experience efforts on Yahoo Search and Directory and has been a practicing information architect for four years. (She is also the founder of Boxes and Arrows.) Despite her pedigree, Wodtke does not want to be mistaken for a web guru.

A guru, in Wodtke’s terms, is nothing more than a critic who prescribes rigid, oversimplified “rules” of website design. Dictating rules is risky, she implies, because inexperienced site planners and designers tend to take them at face value. They operate under the mistaken assumption that following those rules is all they need to do to create a good site. But there simply aren’t enough well-designed sites out there to justify that approach.

Wodtke argues that good site design is complex, nuanced, and context-specific. You have to look at the problem fundamentally and create a plan that serves the needs of your specific users. You have to create a blueprint based on solid thinking.

So, rather than issue orders, Wodtke strives throughout her book to be more like a good teacher, by providing her readers with useful guidelines, principles, and techniques—what she calls “ways of working.” (13) To illustrate the difference between a guru’s rules and her approach, she spends the first chapter of “Information Architecture” amusingly distilling several well-known “laws of web design” into the more practical principles and guidelines on which they were once based (but have since contorted).

For example, she takes on “Users don’t read. Use as little writing as possible.” She first boils it down to its underlying practical guideline: “Write material to be read onscreen with the understanding that the article may not be read to its completion.” (16) Then she identifies the larger principle on which it’s based: “Consider the situation of the reader and the nature of the content when writing for the web.” (17) Both are much more reliable, and applicable, than the original, erroneous rule.

Next, Wodtke offers a handy list of principles of her own, such as, “Be consistent and consider standards” (i.e., don’t break from convention unless you’ve got a good reason). At first glance, some of these principles bear resemblance to the rules Wodtke is so eager to debunk. But as you read her carefully crafted rationale, it’s clear they serve more as appropriate, realistic goals for website design. They are also general enough that they are unlikely to be confused for specific, one-size-fits-all solutions.

After introducing her principles, Wodtke provides a nicely succinct definition of the role of the information architect: “It’s your job to create a design that balances the users’ desires with the business’s needs.” (62). She then discusses how to tackle the first part of that mission: getting to know your users.

Here she goes over the basics of conducting user research: how to gather real (or potential) users, and how to interview them effectively to learn about their concerns and needs. Skipping ahead a bit in the process, she also gives an overview of prototyping and usability testing techniques. This seems a tad out of place here, but as in much of the book, Wodtke doesn’t dwell unnecessarily on the topic, and the text moves along at a steady clip.

Another key aspect of building an effective site is to understand how its users will approach it—what their mental model of the site will be. Wodtke emphasizes the value of getting inside the user’s head. She contends users have three fundamental questions when they arrive at a website: “Am I in the right place? Do they have what I am looking for? and Do they have anything better?” (90) If you can answer these questions, you’re well on your way toward designing a successful site.

From there, you can begin figuring out how to present your content in a way that will make sense to your users. Wodtke discusses several effective, user-oriented classification schemes and the importance of clear, consistent labeling. Many inexperienced site designers overlook these key issues, so it is reassuring to see their value emphasized here.

Having introduced how to approach the problem itself, Wodtke launches into the real meat of the book: how to solve it. Unexpectedly, she doesn’t begin with a site map. That comes later. Instead, she recommends starting from the bottom up—from users to page design to system architecture.

First, Wodtke says, figure out your metadata—the information that helps users find the content they’re looking for. When you go to a shopping site and have to dig around to find something you know the store offers—a scarf, in the book’s example—it’s a sign of bad metadata. If you get your metadata right, on the other hand, you’ve already cleared the first hurdle of effective site design. Wodtke offers several methods for determining what metadata your users will need. Here again, she does an impressive job of conveying the value of a step that inexperienced information architects often skip.

Next, when your user finds the content he’s seeking, he’ll need to interact with it. To design the most pleasing experience for your users, Wodtke recommends thinking in stories, specifically scenarios featuring personas.

Personas are becoming an increasingly common tool in the interaction design field, yet the process of creating and using them effectively has not been widely documented. Here Wodtke hits one of out of the park by presenting a wonderfully concise and complete summary of the technique, which she calls “The Shirley Maclaine Method” (because, while designing, you “channel” the persona, get it?). Wodtke then provides a quick, clear description of how to use scenarios to visualize your personas using the various functions of your site.

The next chunk of the book is dedicated to creating good interfaces, summed up in Wodtke’s five GUI principles:

  • Simplicity and Elegance
  • Proximity and Relevance
  • Focus and Feedback
  • A Hierarchy of Importance, a Hierarchy of Task
  • The Right Tool for the Right Job

Throughout this section, Wodtke illustrates her text with numerous examples of existing websites, often presenting nicely parallel, but different, applications of a given principle. Refreshingly for a book of this type, and in keeping with her non-guru stance, Wodtke delivers all of this as a collection of guidelines and suggestions, rather than a decree. She evenly lays out the pros and cons of the various design solutions she offers, and makes it clear that the best solution is always the one that is most appropriate for your particular situation.

Finally, after a healthy discussion of site navigation principles and concepts, Wodtke comes to the core of the website: its architecture. Appropriately, she goes into some depth in this area. Your first step: start drawing your site on paper or on a whiteboard—avoid the computer at first. “It’s better to scribble ideas on paper with the full knowledge that this will not and cannot be the final product.” (247)

Wodtke suggests two scribble methods in the section called “Drawing for Thinking:” sitepath diagramming, which maps the site from a human perspective, and topic mapping, which maps the site from a content perspective. She provides helpful definitions and examples of the techniques, and encourages readers to try both to see which works best for them. (She even provides a handy sidebar on how to draw iconic people for sitepath diagrams.)

When you’ve got the site plan figured out, it’s time to share it with your team. To do so, Wodtke recommends several visual and textual techniques: hand-drawn or computer-generated interactive storyboards, wall diagrams and functional specifications, content inventories, site maps, and wireframes. For reasons of brevity, or possibly the author’s personal preference, some of these techniques are treated in more depth than others. For instance, site maps have eleven pages devoted to them, while wall diagrams and functional specifications get only three. But Wodtke addresses them all sufficiently for readers to at least use them as a starting point.

Having covered the site planning and design process from bottom to top, Wodtke employs a clever gambit to sum it all up: she talks about a real project. In the chapter “All Together Now,” she tells the story of her client Nick, who asked her to redesign his online magazine, Digital Web. In-depth, real-world stories like this one are rare in design guidebooks (which tend toward higher-level, abstract discussions), and this section is both entertaining and serves to illustrate, as its title suggests, how to pull all Wodtke’s techniques and principles together. Alas, the story ends somewhat abruptly at the wireframe stage, as it would have been nice to read the whole story through to the site’s relaunch. (Perhaps there will be a sequel.)

Finally, Wodtke shares some general techniques for getting your work done: how to break designer’s block, how to present your ideas effectively, and how to get people to buy into your design. She closes with some ruminations on the future of information architecture: the world will continue to become more and more complex as new technologies are introduced into our lives, and it will be on the shoulders of information architects to “protect human beings from drowning in the sea of information.” (329)

“Information Architecture: Blueprints for the Web” is, essentially, a primer on successful website design. Unlike the many dense manual-like books on the topic, the straightforward, accessible, and often funny prose of Wodtke’s book makes it an effortless read. Novice IAs will find good ideas and techniques flowing into their heads, while experienced designers will find themselves nodding theirs in agreement. And the clear, well-labeled organization of the material makes it a handy reference for both audiences as well. So grab a copy of this guide, and if you find yourself in my situation, in which someone asks you to recommend a book that concisely describes what it is we all do and how to do it, you’ll have an answer.

Read a chapter (PDF) from “Information Architecture: Blueprints for the Web.”

  • Information Architecture: Blueprints for the Web
  • Christina R. Wodtke
  • New Riders Publishing, October 2002
  • ISBN: 0-7357-1250-6
  • Softcover, $29.99
  • Chapters:
    1. Gurus and Rules
    2. First Principles
    3. Balancing Acts—Users, Technology and Business
    4. Those People
    5. Sock Drawers and CD Racks—Everything Must Be Organized
    6. A Bricklayers View of Information Architecture
    7. From A to C by Way of B
    8. Eat Me, Drink Me, Push Me
    9. Making It All Up, Writing It All Down
    10. All Together Now
    11. Being Effective
    12. And In The End
  • Companion website []

Ryan Olshavsky has nearly five years of experience in interaction design and design documentation. He is currently an Interaction Designer at Yahoo! Inc., a small Internet company. Previously, he worked as a design consultant at Cooper.