What’s the best way to document design decisions? UX Question #52

Watch on YouTube

YouTube player

Listen to the podcast

Read the transcript

Hannah B from Seattle asks: What’s the best way to document designs and design decisions?

I love that question. Thanks for asking, Hannah. This is UX Question number 52 and I am Ben Judy.

What’s the best way to document design decisions? I’ll answer this by sharing how not to do it.

I’m reminded of my time working as a UX designer at American Airlines. The AA.com team had business analysts who would create massive documents called BRD’s—Business Requirements Documents. They would annotate our UI designs with business logic and rules around where the data would come from.

It was an enormous amount of work for some very detail-oriented people who did very little to improve the user experience. I say that because there was nothing in those fat binders of documentation that had anything to do with the qual and quant user research we had done, or findings from usability testing, or UX best practices.

Inevitably, what the developers got was a mountain of paperwork describing how the business wanted the technology to work, and very little understanding of what we knew about our users and their needs. So my first tip for documenting designs is: share the user research.

Secondly, those BRD binders were all about functionality, not about the user experience. Flipping through page after page of technical specifications surrounding our UI mockups, you lost the design intent for creating a great user experience. The flow of what the user did and how they felt about it was not communicated. We need to describe the intended user experience, not just the nuts and bolts of the product design.

Thirdly, that design documentation back then was incredibly dry and technical. It was written for the developers and QA testers, but it did nothing to get them excited about building what we designed. And it certainly wasn’t anything that our stakeholders running the business wanted to read. Anyway, the developers and testers could just talk to the designers to have a conversation about the intent, and we did have those conversations. We missed an opportunity to craft a description of the design intent that would rally the team behind the design vision, and build empathy for users, and inspire all of us to create something awesome for our customers.

Fourthly, it wasn’t concise. The most important design decisions were lost in favor of being comprehensive. The most impactful moments in the user experience were just another line item alongside rare and unimportant edge cases.

Based on that experience, I recommend you document designs like this: share the user research, describe the experience, inspire your audience, and focus on moments that matter.

Keep asking your questions about UX. Next time, I’ll answer the question: Where can I study UX?

Referenced in this episode:

Support UX Questions

Visit us on Patreon and check out the great perks at each level of support!

Become a sponsor

You can advertise your products or services—our promote yourself as a UX professional—by sponsoring episodes of UX Questions! See the Sponsor page for details.

Hire Ben Judy

Ben is available for consulting engagements as a workshop facilitator, mentor, design coach, and more! See the Ben page for details.