I was speaking with a colleague recently about design system marketing. One of the problems I’ve seen is a person coming into design system resources and being immediately overwhelmed by the options. Hick’s Law strikes again. I’m not just talking about looking at a code base. This is the case for popular public design systems too. As much as I admire Adobe’s work on Spectrum, it’s very easy to be intimidated by all of the stuff they have featured in their documentation.
To illustrate this, I like to use an analogy that I call Storefront & Warehouse.
Getting needy
Let’s say you are looking for a new vacuum cleaner. You aren’t picky, you just need something that can clean dirt and pet hair from wood floors on occassion. You walk into a store, find a vacuum that looks good enough, and take it home. It work fine, nothing to be excited about. You got what you paid for and everything is good.
Now, let’s say you do have some additional criteria for your vacuum. Maybe, you’d prefer that the vacuum was red to match the furnishings, so the appliance blends in better with the room it’ll be stored in. So you walk to the store, and you don’t see any red vacuums on the shelf. You find a stock person and ask if there’s any red vacuums in the back. He comes back and says that the company makes custom plates to change the color. All you need to do is order the plate and your vacuum will be red. So, you walk out with a regular vacuum and change it to be red afterward. You got what you were expecting, even though it took a little bit of extra work and everything is good.
Now, let’s say you have a very specific desire. You want a vacuum in the shape of a standing lamp, so it really disappears when not in use, or better it can be used as a lamp while standing in the dock. You go to the store and look but there’s no vacuum like that on the shelf. You ask a stock person, if they have any in the back. This stock person loves the idea but knows that there’s no such vacuum in the warehouse. However, the warehouse does have all of the parts to make it. So, the stock person graciously gives you access to the warehouse so that you could build your own. It takes you a while to find all the pieces and figure out how to put them all together. In the end, you finally have precisely the vacuum you’ve been looking for and everything is good.
Struggling at the store
Instead of picturing something walking into a store and looking for a vacuum cleaner, think about it as a peer navigating to your design system resources looking for something they need. In some cases, it’s right there on the shelf. Some times it’s not quite what they need, but with a little configuration, it would be acceptable. And other times, a person would need to scour across different pages to collect the information needed to make exactly what they have in mind.
There’s increasing struggles in these cases when we think about how we publish about documentation. For example, some documentation sites make you feel like walking directly into the warehouse. You see all the vacuum cleaner pieces but the ones that work off-the-shelf are mixed in with all the parts. It’s not immediately clear where to go for the thing you are supposed to work with. There’s no storefront. I’d argue many large public design systems are guilty of this problem. With so many options, it’s hard to choose which is the best option as said earlier.
For folks who find the resource that looks close, sometimes the options aren’t clear. It’s like going to the store and never finding help to let you know that you can customize your vacuum cleaner. Instead, you leave the store and go try another one, or get a vacuum from the shelf and paint it red. In either case, it would have been better if you were informed about the customizability right there on the unit when you first saw it. No need for a stock person to find, the options are clear.
And finally, for folks that are immediately disappointed because they visit and don’t find anything that they need, this is the hardest to support. And unfortunately, this is something that I believe happens most often. With the rapid iterations of product design, no design system could possibly keep up with specific features. So, it is very common for people visiting resources to not have the time or experience to search for pages of documentation, tinker with some of parts, and craft something that aligns with the system. Often times, people believe it is faster to just make it without using the parts. I think with poorly documented design systems, this might very well be the case.
Think about it. If the resources in the design system don’t align well with the visitor’s mental model. It’ll take time for that person to read the documentation, get an understanding of the approach and patterns, build something with the parts, and finally integrate with their application. On the other hand, if the person builds it without adopting a new mental model, they still need to build the feature, it just might be with more individual parts. Importantly, these are parts they are familiar with. It’s that familiarity which equates to the speed of building and meeting the need of the product more quickly.
That’s why so many resources often align with a person’s mental model instead of more unique presentations, even if that unique presentation is better in any way. It’s why early GUIs speak about a desktop and folders instead of a terminal and directories for the public. It aligns with existing mental models of working in the physical world. This means that introducing something better but novel will be most successful when alongside an existing mental model.
In other words, if we’re going to offer a way to build the lamp-vacuum, when a person walks into the warehouse it should be immediately clear which parts they’ll need without being totally lost amongst all of the other unncessary parts.
Search first
Years ago, we had to walk through a store to find the place where they kept the vacuums. If I’ve been to the store before, maybe I remember where they’ve been kept. Hopefully, the store didn’t go through a redesign moving the items around, because my mental model of where the items are stored will make it faster for me to get to the thing I need.
Now, some larger stores like Home Depot have their inventory locations available through their mobile site. You pick the location you are visiting, search for the item at that location, and the website will tell you where that item is in the store by aisle and bin. This way, you can go directly to the item you need without walking through the whole store, learning the layout, and hopefully landing on the thing you needed. This also avoids the possibility of you missing the item through the vast amount of aisles and products. You have confidence what you need is there and where it should be.
This is why I find the exercise of creating navigation for a documentation site largely useless and potentially even harmful. Finding the thing you want is rarely useful in a wandering scenario. It is more helpful to zero-in on the resource you are looking for by aligning with your mental model. If you are from the UK and you look under “H” for hoover, you wouldn’t find any vacuums because the are listed under “V”. That would make the visitor assume that you have no vacuums because the information architecture doesn’t match their mental model, and they’ll leave empty handed because of your IA. IA that was intended to help makes people leave disappointed.
Meanwhile, a robust search experience could make the connection internally. Searching for hoover could alias to vacuums and produces the appropriate results. That way, searching could return results from the storefront first and warehouse after.
This sort of search experience is common for icons, where a person looking for the “close” icon should return for the same result for “x”, “dismiss”, etc.. There are other systems that even let a person draw the icon to provide results. We could imagine this expanding to components in our documentation sites.
The hot take here, drop the exercise of figuring out the IA of your documentation site, and invest time in a robust search. In the world of artificial intelligence, leverage that to match mental models instead of deliberate aliasing. It would be best to meet people where they are, without causing them to visit external sites and learn opinionated IA. But if you don’t have the resources for AI, make search site-wide and fuzzy af. That gives your visitors access to the whole storefront and warehouse, but raises the most appropriate resources for their needs.