Foundational UX

Design Rationale Documentation

August 22, 2022
Written By:
No items found.

Consciously or unconsciously, you’re being influenced right this second. Taking in information and processing it into memories, insights and, perhaps, new rules to live by. This is the joy of having a delectable, a-hem, discerning brain that drives your decision-making. So much of it happens without any awareness… can you imagine being asked to track back and identify the initial seeds that sprouted any one notion?

As UX Designers? Yes, we can imagine that. Because it happens to us all the time.

Being asked to share the set of logical bases that form the foundation on which we build every feature, tool and digital product we produce? Oh yeah. We get asked to share the rationale behind our designs on the daily. And that’s sometimes a scary request because by nature it’s in a constant state of evolution as we build. That’s why creating Design Rationale documentation is critical.

What does it mean to document your design rationale?
You might document your specs, user stories, development documentation or have a product decision log. This is a bit different. Documenting your design rationale is simply the practice of writing and logging decisions related to the product, feature you’re working on – it works best for complex feature sets which have a lot of moving parts. It happens regularly and allows you to go back later and figure out, wait, why did we do that?

Your design rationale documentation should serve as a log that outlines the bases for the big decisions relevant to your project. The log acknowledges that yes, designers are human, we forget stuff and sometimes get confused. Having multiple conversations on a topic, with multiple stakeholders and various users can really impact our ability to make rational decisions. Logging our thought progression helps us remember what we were thinking and why.

Just like a living thing it needs consistent and diligent tending, particularly in the complex world of Enterprise UX and SAAS products. This takes a fair amount of work and, we’ll admit, regularly falls off the side of the desk but, speaking from recent experience, it’s worth the effort not to let that happen. If you lose the plot and let your Design Rationale die, it will come back to bite you. 😱

You might start your project by outlining your well-intentioned design principles and parameters, but do you log the big changes as your thinking evolves? If you aren’t diligent about keeping your rationale fresh, it spoils real quick. Instead of a healthy and functional guide, you’ll find yourself with an uncanny unrecognizable shell of what it once was…

What is this certifiably grotesque concept, you ask? We’ve coined it Zombie Rationale, and we’ve got a whole host of reasons why we’re aiming to eradicate it. One well positioned habit and process at a time.

Documenting Design Decisions (and Rationale)

Think of Design Rationale like a spec document, but instead of focusing on the what, we use it to track the why. We start with the high-level design principles underpinning the project. What are the foundational pillars? What are the rules of engagement? The principles and directives we outline here then serve as a lens through which to view and prioritize all of the design decisions that follow. These foundations can continue to be groomed over time, but will holistically serve as a mainstay that the whole team can lean on to stay aligned. If your team struggles with scope creep, this high-level effort can really help keep the true objectives of the project top of mind, even when you’re deep in the weeds in late-phase project cycles. Documenting your design decisions happens at various ‘zoom levels’ design principles form the basis for the more specific design decisions you make during your workflow.

Example design principles

These are some examples of design principles that we’ve used in the past (across various projects use cases and domains)

This complex software had a historical issue of not telling users what’s going to happen when and if they execute a certain action, this led to disastrous losses of work in the platform due to misunderstandings and the UI taking a ‘passive’ role in their workflow. This ‘hidden’ logic was exposed through a host of features, UI patterns and content considerations.
This complex software tended to take a ‘more is better’ approach to exposing information to people, whether that was data visualization (dense visualizations and a lot of them), data tables (many columns without much focus) or their home screen, which exposed #allthethings
s us understand what other organizations have done well or have done poorly, and what market trends may influence the design.
Hierarchy and interconnectedness between things in this product was key to making sure we could reduce user error which led to a lot of time wasted and errors. In fact, if one thing went wrong when defining relationships, this could mean that up to 2 days of time spent for processing a specific ‘run’. Validation in the backend couldn’t find these issues, so the ability for users to visually QA and verify the info was needed in order to prevent this.
This product, although rich in information aimed to get people ‘hooked’ by way of exposing them to the possibilities the data presented for humans to connect. Rather than exposing high level stats and figures, we opted for more ‘soft’ approach to making data and functionality discoverable to the audience.
What it is
Observing people in their natural habitat to understand how they do things.
This product historically involved a lot of repetitive tasks. Going forward it was key to make sure that power-user efficiency was considered. This was exemplified through batch actions, multi-select, drag and drop, keyboard interactions and many more UI mechanisms.

Once the foundations are captured, we move into more granular logs. We outline the objectives of each feature area and dive deep into areas of complex functionality to zero in on specific rationale. We’ve found a combination of writing, sketching, and video walkthroughs seem to be the best methods for articulating these particulars. Though amending video content tends to be more of a lift, so we’ve taken to relying on writing and sketching in our recent documentation. This is also the more amorphous part of the project that is more likely to change, so facilitating easy updates is key. Groom and prune to keep these specific but critical pieces of your Design Rationale healthy, and make sure the team knows that effort is underway.

Design rationale examples

Let’s just take a moment, to take this from an abstract concept to a concrete one, with some handy design rationale examples.

Anatomy of a design rationale section

Anatomy wireframe of a design rationale document

Basic elements of a design rationale document section:

  1. Feature title (or functionality description)
  2. Description of your approach or way of thinking
  3. Logic behind your approach or reasoning
  4. Detailed information (either visual or links etc)
Example 1: This is an example of a starting point for a search feature.
← Earlier
Later →

How we got bit by Zombie Rationale

Our focus on logging Design Rationale at P&P labs started when we ran up against some undead rationale. At some point between mapping out our initial wireframes and moving into hi-fi design, we found a handful of infection zones. We had our product spec document outlining what we were going to do, but we’d failed to update a few key steps in the why.

From its fledgling state at the beginning of a project, a healthy Design Rationale mutates repeatedly over the project lifecycle. As this happens, decisions form dependencies on one another, resulting in a cumulative decision tree that naturally builds upon itself. So, what happens if you let any aspect of this iterative, layered decision-making die?

We let our attention stray from tending to our Design Rationale, and it jeopardized decision-making faster than a horde of the undead breaks down a rickety barn door. Luckily, we caught it and were able to update our documentation and move ahead, more heavily armed (with wisdom). But, had we left it just a few weeks longer our client’s confidence in us most certainly would have gone the way of every 90s horror movie subplot character. As frustrating as it sometimes feels, stakeholders are always going to be there asking you to validate your decision-making, and like it or not they’re justified in asking. So, when they catch you off guard with a decayed rationale and you come up short on explaining why; your options are to either come clean or attempt to retroactively cobble something eloquent together in real-time…

No shame. We’ve done it too. But upon further exploration, we’ve identified just how damaging this practice really is. Off-the-cuff rationale like this lacks the dynamic and nuanced nature of the real thing, even if you feel like you’ve kept a good handle on how it’s unfolded. In a pinch, it serves as a short-term escape route, but it neglects all of the heart and history of the process.

A healthy Design Rationale evolves and expands, telling us everything we (and our collaborators) need to know about how we arrived at our final deliverable. On top of that, it shows how much effort has been put into each judgment call, and that deserves it’s due.

Characteristics of a healthy Design Rationale Documentation process

So, how do we keep our rationale healthy and avoid projects ending in a Zombie Rationale Apocalypse? We’ve got a plan to eradicate undead vibes and keep our (and your!) Design Rationale current, accessible, alive and human. But first, some ground rules that should help keep your Design Rationale fresh and lively.

Spans the project lifecycle

If you’re going to commit to this best practice you’ll want to do it right, and that means launching at kickoff and maintaining it through sunset. If managed correctly, this project-long effort will result in a dependable resource for all. It’s a non-trivial burden, but the payback is well worth it: increased confidence in decision-making, improved clarity, team-wide knowledge building, expedited information dissemination, reduced design hours, more seamless design to dev handoffs, and more trusting clients. As long as you maintain the integrity of your documentation to ensure that the resource remains reliable, you can expect to enjoy all of these improvements – and more!

Living, Dynamic and Considered

A dynamic, evolving guide like this one that serves as a source of truth requires consistent updates. Letting go of any preciousness around version one is key, and the more detail the better as your thinking expands. That being said, this documentation doesn’t need to (and shouldn’t) be a log of every single deviation of thought. It should consist of only the most integral decision making progressions. Don’t undercut this effort by trying to log #allthethings and inadvertently allowing your documentation to fall out of date. If stakeholders determine that the rationale is no longer a viable source of truth, you’ll let expired rationales creep their way into your project down the line. Keep the rationale as concise, current and considered as possible, and you’ll be pleasantly surprised at how much you can learn from distilling your team’s initial thinking down into a more accurate and precise set of rulings and recommendations.

Take a Unique Approach

The dynamic nature of this effort also requires a commitment to treating each design decision with a critical eye, even in cases where the context mirrors other previously built features. There are so many excellent reasons to prioritize design consistency in Enterprise UX – design and building efficiency, product usability and user experience, to name a few. But, you also need to leave room for the possibility that although the contexts may mirror one another, the rationale might fail in this specific case. It’s a classic error: repurposing a previous line of thinking without a critical lens and realizing down the line that the rationale can be chalked up to ‘it’s what we did last time.’ Beware! A few too many situations like this and you’ll find yourself back in the danger zone.  

Do yourself a favor and treat any connections to similar projects as helpful anecdotal context (as opposed to a reliable feature roadmap).

Reasonable and depersonalized

A healthy Design Rationale is always reasonable. If a stakeholder asks why a decision was made and the response is ‘because we liked it,’ we’ve surpassed rotten rationale and moved into a whole other realm of bad. Design Rationale in Enterprise UX should be objective, meaning that any informed stakeholder should be able to understand and repeat the rationale confidently. Offering a logical and communicable foundation for each of your design decisions that everyone can point to will ultimately go a long way in exhibiting the strength of your collective design expertise and professionalism. In the short term, this depersonalizes the foundations of your project and ensures that your team is aligned. In the long-term, it future-proofs your efforts well beyond the span of the project timeline and client relationship.

Additionally, even if you’ve got the juiciest brain out there and can accurately and confidently maintain your own morphing Design Rationale, it’s only available to you. In Enterprise UX, we are almost always working as a team. Allowing a single team member to gatekeep the project Rationale isn’t only ill-advised, it’s foolish! Without a log of why there’s no way to ensure the full team is aligned and prepared to speak to the decisions that the team has made. So what happens when the team changes, a lead designer falls ill, or a personal emergency keeps a stakeholder indefinitely offline? Documentation ensures that the whole team understands the rationale and can pull on it as needed – it’s an invaluable stop-gap strategy as well as a useful onboarding resource. Don’t be greedy, share your brain! 🧠

Owned and operationalized

Though a project team should collaboratively review and amend the Design Rationale, there needs to be a primary owner. Keep in mind that the right person for the job will depend on the team you have. A project manager could carry the torch, but will they understand all of the inherent nuances? Will they accidentally miss boarding up the cellar door and let the Zombie hordes infiltrate? The lead designer is less likely to miss critical details, but will they have the time to get the job done before they stagger to the door, one foot dragging behind them? Ultimately, your unique team and project will require a unique approach.

Selecting the right owner is arguably the main ingredient in this proposed eradication strategy. The owner must be skilled in documentation, knowledgeable in design, communicative, and highly committed to consistent maintenance. Additionally, they need to feel empowered to operationalize the information on a day-to-day basis to ensure the rationale stays current and top of mind. Read: the lead on this needs ‘Columbus in Zombieland’ main character energy, y’all. Making numbered rules and keepin’ everyone in line.

Articulating is knowing

Still feel like detailed Design Rational documentation like this is excessive? Here’s the kill shot: you may believe you’ve got your rationale on lock, but there’s a high chance you’ll miss critical information when it comes time to speak to your work and build the thing. Our brains are wired to layer new information on top of our pre-existing memories, so every time you look at a design you’re modifying your perceptions of that design. These subconscious modifications shift you further and further away from your initial rationale as your designs evolve, and you probably won’t notice.

Even for the most detail-oriented of us, expecting to maintain an accurate mental map without physical documentation that tracks lifecycle-long design decisions is an unreasonable ask. Us living humans, have a lot of cognitive ability, but even we have our limitations. Plus, without a log of these changes, you won’t get the added benefit of being able to track how your own rationale changes over time as you learn and grow, which, in our experience, has been one of the coolest outcomes of this new practice. It’s a commitment, but it’s worth your while.

How we work as knowledge workers is changing

We feel that times are changing. It used to be that the ability to draw a quick answer to the why was what instilled confidence and indicated a strong grasp on the project particulars. But these days, people don’t want to be soothed… they want accuracy. Providing off-the-cuff rationale may have been the way at one time, but we’re finding that now it’s taking the extra few moments to pull up and re-familiarize yourself with the evolution of your thinking that breeds confidence and respect from your stakeholders.

It’s not your memory they’re looking to scrutinize, it’s the true rationale on which their product is being built that they care about. Plus, the positive results we’ve identified internally since moving to this process have only increased our motivation to keep our documentation healthy. Ultimately, our Design Rationale serves as a contract we enter into with the optimal user Experience we intend to provide. We’re not just writing stuff to write stuff, this  process results in better, more robust thinking itself. Which, as knowledge workers, the thing we’re supposed to be good at.  We all want the same thing: to design better products and maintain better customer relations.

Download our Table UX Audit Checklist

Do a mini UX audit on your table views & find your trouble spots with this free guide.

Available in a printable version (pdf).

Please fill in the form below and it will be in your inbox shortly after.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.

Want to dig deeper on flow diagrams?

Be the first to know about our upcoming release!

If you found this intro content useful and find yourself needing to express yourself more efficiently on your software team, this training is for you. Our new flowchart training includes real-life enterprise stories and examples for using flowcharts for UX. You’ll get tips on how to make your diagramming efforts successful, how to derive info for the flow charts, and how to get others to use and participate in the diagramming process.
Thank you! Your submission has been received!
Oops! Something went wrong while submitting the form.
Contact Us

Intro to UX for Teams

Learn the foundation that P&P uses to think through all interaction patterns, including errors, success and warnings

55 min
$90 USD

Explore our UX/UI Services

Curious about the possibility of working with the P&P crew on your enterprise software project? Check out our services.

Our services

Join our newsletter

Bringing enterprise-grade UX resources into the world to help you think better and have more interesting conversations with your crew!

Newsletter sign up

Data Tables Checklist

This free checklist lets you double check your data tables for their UX quality and assess various aspects which make or break the data table experience for your users.


Explore our UX/UI Services

Curious about the possibility of working with the P&P crew on your enterprise software project? Check out our services.

Our services

Join our newsletter

Bringing enterprise-grade UX resources into the world to help you think better and have more interesting conversations with your crew!

Newsletter sign up
Previous Post
Visual Hierarchy in UI
Next Post
A Guide to Leveraging Power Users in Product Development