The U in Team
In Search of the Design Documentation Unicorn
My friend Christina Wodtke posted this question to Twitter:
What is the single best resource for how to document the interaction of an app in its entirety for a PM and engineering team?
Ah, documentation. The topic every designer loves to hate and hates to love.
Christina isn’t asking for the single best method or tool. She’s asking for a resource that helps designers understand the range of concerns that come with documenting software designs. It’s easy to misinterpret this as “What’s the best way to document software?” The simple answer is, there isn’t any.
1. Build a Toolbox
Documentation is, by its nature, an abstraction. It takes a complicated idea and squeezes out some of the aspects that make it complicated so that you can talk about the important parts. You’ll create multiple artifacts to discuss the product from different perspectives. These abstractions are super important as products become increasingly complex. But there isn’t one right way to abstract for every situation. Different assignments call for different perspectives and different approaches.
Designers therefore need a range of tools to draw upon. To communicate the priority of content on a page, a wireframe is a pretty good tool. To engage in discussions about the way users move through an app, you can use a storyboard. None of these are better than the real thing, but they are good intermediate steps to facilitate conversations. As teachers, our responsibility then is to expose students to a range of tools:
The ability to consider, evaluate, and learn a new tool, so that it may be added to the tool box.
2. Talk to Engineers
I’m always puzzled by designers who are dogmatic about their documentation formats, tools, and techniques. Designers need to build a toolbox of techniques because every job needs a different approach. The right approach for your job depends on so many factors:
- What are you designing?
- Who is using the documentation?
- What format/content would be most helpful to them?
- What development framework are they using?
- How important is it to keep the documentation up-to-date?
- What artifacts worked best for this team on previous projects?
Talking to the development team, the ultimate consumers of the design specifications, gives you the main input you need. Like any user, they may not know exactly what they need (or what you can deliver) but talking to them you get insight about what would be most helpful to them.
The more tools you have at your disposal, the more flexibility to craft a good approach. Not every team wants the same thing. We’ve worked with teams who love high-fidelity prototypes and others who still need decks of wireframes. We’ve helped teams mature to the point where we can draw a sketch which translates to reusable components from a design system. We’ve worked with start-ups who will take hastily assembled prototypes.
[Insert here: ridiculous metaphor to carpentry or surgery or watchmaking or any other craft in which a range of tools has developed.] The choice of tool depends on so many factors, and it takes experience to know the right one. For us designers, we rely on our expertise to guide us, and part of that expertise is asking the right questions of the people who will use our artifacts.
While exposing students to a range of tools, teachers must also help students understand what to ask and look for:
The ability to see all the factors that influence our decisions about our approach.
3. Adopt the Right Mindset
In Designing Together, I describe three mindsets essential for designers. A mindset is more than an attitude: it’s a lens by which you perceive situations and a mechanism for deciding a plan of action. Without an Adaptive mindset, a designer treats every assignment the same way. They think they can apply the same process and deliver the same outputs. Part of our jobs is to assess the assignment and determine the best approach, which may entail combining tried-and-true methods with something new.
Over the years, EightShapes has used these techniques for delivering designs:
- PDF of annotated wireframes
- HTML prototype with PDF of annotated screenshots
- HTML prototype with PDF of wireframes of additional screens
- Prototype in proprietary software (like Axure)
- Stand-alone custom-built HTML site
- ZIP file with components rendered in both .INDD and HTML/CSS
In every case, we considered multiple approaches, usually arriving at the end product by weighing the project needs.
As one person put it (I think it was Mike Monteiro), as a designer you’re designing the process as much as you are the product.
Formal documentation faced a backlash over the last several years, as many teams found their designers preoccupied with the artifact and not the product. Perhaps these designers became too rigid, and neglected to adopt an Adaptive mindset. They chose to look at every assignment through the lens of the requirements-flows-wireframes framework they’d used time and again. With an Adaptive mindset, you embrace the perception that every assignment is a chance to challenge your preconceived notions of the right way to do things.
Those who teach young designers must help students develop this mindset:
The ability to weigh different approaches to the assignment, even if it entails new tools and techniques.
4. Learn to Listen
Christina is a teacher, a fact more than any other that gives me hope for the next generation of designers. Knowing this, I read something else into her original question: How do I teach new designers to document correctly?
Documentation (and communicating intent) is a design exercise. Designers need to be great at this because it belies an underlying understanding of how design works. It may seem counter-intuitive, but the key to great documentation, like any form of communication, is listening.
Hearing and internalizing the needs of the development team is as important as doing so for the needs of the users. The desire to document every last function may not be what the team is asking for. When they say “We just need to understand the exceptions” your response shouldn’t be defensive (“I need to document the whole thing!”) or even blind enthusiasm (“I’ll make a specification!”) Your response is more questions:
- What about the exceptions do you need to understand?
- How well-understood is the happy path?
- Which exceptions are you most worried about?
- Can you show me an example of how you’ve documented exceptions previously?
- How do you plan to work on the exceptions?
And perhaps to suggest a group activity like, “Can we spend a few minutes free-listing scenarios so we can make sure we’re on the same page?” Yes, we need to make sure students understand the range of tools currently available, but we teachers must help them to cultivate a crucial skill:
The ability to nurture an inner skeptic who’s great at asking provocative questions.
The real document isn’t the artifact. It’s the conversations that happen between members of a team.
Maybe you didn’t know this, but I wrote a whole book about design documentation. You should get a copy!
It’s a cookbook of design artifacts, examining different ingredients of documentation and how to assemble them into a meal.
