Why you should document your UX product specs.
By: Zhiyu Xue
Tags: Design, Design Systems, UX, Design Process, Product Design

Last month, I was working on redesigning an annual benefit statement that will be sent to the whole company at the end of the year. Considering the fact that design was done five years ago, we decided to give it a UX touch before we turned it to visual designers to redesign the look and feel of the statement. Therefore, I started to research and design information architecture for our benefit statement.

From a user perspective, the project merely seems like just a statement of what benefits you received that year. However, it is way more significant than it looks. As I mentioned, this benefit statement would be sent to the whole company, that means we have nine different countries for whom to design. Every country has an entirely different set of benefits — not to mention different languages, currency system, and legal requirements that may apply.

With so many different regions, one universal design might not apply to all the areas. Because some countries give a couple hundred units in their currency and some countries give millions of units; some countries are required to display every single detail and policy in the benefit calculation, and some countries present a total number of benefits.

My original plan was to design nine different versions for every region, but after I finished the first region, I died a little bit inside. I was afraid of adding or removing content without checking with HR considering it can be legally required. With that said, I started to look into a better way to work on this project (once was enough, really). The “lazy” way of thinking is to consider what’s out there that can automatically finish this for me. I don’t remember what my thought process was, but Google Material Design Library inspired me. Design different UI elements to display different benefits and make a guide for Dev to build them. Basically, a guide says in this situation use this table in this way.

I analyzed the content in every region and designed tables that can fit different materials. Creating this guide ended up taking more effort than designing nine versions. However, I learned so much by developing a design guide than actually designing a product, and I would love to share it with you:

What UX Product Specs I built and Why

image from http://atomicdesign.bradfrost.com/chapter-2/

From my mentor, I learned that what I built is called UX product specifications. Similar to the visual design style guide, UX product specs should document the reasons behind your UI element to an atomic level (Atoms are the smallest UI element such as labels or buttons) by describing its usage. In general, UX product specs include all your UX design work documents, such as problem statements, the sitemap, workflows, and annotated wireframes. Depending on your audience (dev team or stakeholders) you might want to include extra information designated for them. There’s no standard way to convey this information because it is all dependent on how you want to communicate your design.

In my case, I was inspired by Google Material design. I found it beneficial for adding “dos” and “don’ts” because we might set some UI elements to behave a certain way, but it might mislead developers (or designers) to use it differently. For instance the Material Card Design Spec: When you look at the “don’ts” example, the product specs have defined the element and its behavior. However, when you look at the “dos” example, it is a better design behavior because it doesn’t break the context from the content. When your product specs have a lot of UI elements defined, there are many possibilities to create a molecule that obeys the product specs but not necessarily work well with the content. Therefore, understanding “dos” and “don’ts” is very beneficial for helping your audience develop based on your product specs.

If you are interested in reading more about how to write general UX product specs, I found Chris Kiess’s guide very helpful.

Better understanding, validating, and showing your design

As a designer, you are often asked to present your design in front of a group of people. They can be engineers, stakeholders, product managers, or your fellow designs. At those presentations, people will always ask you why you designed it a certain way. As a young designer, like me, you can be too panicked to justify your reasoning behind those design decision. In that moment, you will lose trust from your clients or stakeholders.

I am not going to say writing product specs are the way to solve those problems, but it helps me rethink my design decisions and memorize them by writing them down. Honestly, sometimes we are so comfortable with our design work and decide without having a second thought. Enough so that we might miss opportunities or not think about the reason behind them. When writing down the anatomy of the UI element, it is time for you to slow down and rethink every single detail. So hopefully, when you are asked to justify your design decision, you will answer the question the way you want.

Help Engineers know why you designed this way

Think about the situation above. Designers don’t always get a chance to present their design work in front of the dev team. Sometimes, the dev team might even be offsite or across the ocean. Now, other than giving them wireframes to build off of, how can you clarify the design decisions or help engineers understand your vision? The UX product specs now become an honest blueprint from you to the engineers.

Often when engineers receive design comps, they don’t agree with them. I was surprised when I heard that idea from one of our dev teams, but it’s actually not that surprising. I remember there was a dev team from overseas who didn’t want to “waste” their time to build the design work when I was interning at a design consultancy firm. I am not saying design specs can fix those problems but at least it gives designers a way to articulate their reasoning. You might think an intuitive design doesn’t need explanation, I would agree if the audience consists of users, but an intuitive product is not necessarily a design for engineers to build. A product specs should give them the insight of why the designers made the choices they made, and if engineers/stakeholders want to validate the choices, we should include the research in UX product specs.

Help other designers if they will pick up this project in the future

I asked my mentor how to measure good product specs. He said, “if you get hit by a bus tomorrow, I would expect developers and designers can continue the project without you.” I am so sad that no one cares if I get hit by a bus but I agree that a good product specs should have enough information to carry on the project without my presence.

To be honest, I wish the previous designer who worked on that benefit statement left a UX specs for me (maybe they did but the specs were lost over time). So I could feel more confident working with statements that need to meet legal requirements in other countries.

However, I hope my UX specs are good enough for other designers to redesign the product in the future if they need. At least, I think they won’t struggle as much as I had to.

Unify the design language

There was one time we received email feedback from one of our stakeholders. She used a word — backsplash — in the feedback. So our team was guessing what she meant by backsplash, whether it was the landing (splash) page or something else. We messaged her, called her, emailed her and even had a couple internal meeting to talk about what the feedback meant. A week later, we found out that backsplash page was the page behind a pop-up model. The conversation would have been so much easier if we set a unified language between us. And I think the missed opportunity is the product specs, because when you annotate your screens, you will name every UI element within the screen. That way, when people who don’t speak the same design language are trying to communicate with you, they can refer to the names in your product specs so it causes less confusion.

The current design industry is still very messy. There are so many different creative ways. People use so many different words to name something similar depending on where you learned design. So product specs can help communicate even within the design team. It helps to set up a “bible” for a product.

What can I do better next time?

Just a couple of things I wish I did and will try to do next time.

Start documenting product specs at the beginning of the project

Use product specs to communicate within the team

Keep product specs up to date and follow it as the “bible” for the product.

I know some companies require designers to document product specs. We don’t require it because we work very closely with our dev team. However, I still think it is very valuable to document product specs, and it is not just something you do because of work. It effectively facilitates your design communication.

Citations: