Introducing uniform.hudl.com

Building the documentation site for our design system, Uniform, took a lot of research, tons of iterations, and just a bit of rolling the dice. Let’s discuss how we went from multiple sources of truth to just one, and what we learned along the way.

Define Our Goals

We’d known for a while that our old docs were lacking. What we didn’t know was how lacking it was and how much the user cared. It was only when we conducted an internal anonymous survey that we got an idea. To our surprise, people weren’t clamoring for more components or assets — they wanted better documentation.

Comments like this helped us prioritize the documentation itself.

Not only were our multiple sources of truth becoming a burden for us to maintain, they were also becoming a burden to use. So we took this bit of qualitative research, reached out to our users to dig a bit deeper on some things, and decided what the new site needed to accomplish:

1. Bring it all together. This was the no-brainer. Our users were tired of visiting multiple sites and not finding what they were looking for.
2. Build it using our stuff. We have a robust design system. Why not put it to good use?
3. Contextualize it. The site needed to serve both designers and developers without overwhelming one or the other. We also wanted to address platforms beyond the web to ensure every team can find what it needs.
4. Make doing the right thing, easy. We want our internal users to adopt our design system for the betterment of our external users and making it easy to do is the best way to make that happen.

Build One Site for Everything

Our users said it best: Documentation was all over the place. We had Get Started guides in Confluence, component implementation details in GitHub, and code snippets on a completely separate internal site. All of that pinballing was taking its toll on the user.

When users have to think about where to find information, you’re doing it wrong.

It can be easy to fall into this trap when you build something as complex as a design system, especially one serving so many products and platforms. Not having a firm documentation strategy in place was a major pitfall. It became the most critical piece of feedback we received — which made that fix the most important to get right.

Our release notes are a great example of content that would have previously been scattered all over creation. Now they’re in one spot with all the info and guidance a user might need.

Luckily, it’s an easy problem to solve — we just needed one spot to put it all. Instead of explaining things on our internal site and shuttling our users to GitHub or Confluence, we should be giving them all the information with one well-built site.

Use Our Existing Stuff

Although the old site followed the Uniform look and feel, it wasn’t built with our React components. This felt wrong. There are many different ways to build a docs site, but we knew we wanted to use our own bag of goodies for a few reasons:

1. It’s a great way to show off how well it works. When the user sees something as extensive as the site built using the components we’ve been making for the past year, it builds trust in the system and gets people to want to use it.
2. What better way to put your system through the wringer than using it yourself? We found bugs, improvements, and ideas for new components just by using the existing system.
3. It allowed us to build some great interactive pieces of the site that may not have been possible had we started from scratch or used a third-party setup.

Make It Friendly to Any Role

Our site needed to serve both designers and developers, but how do you do that without needlessly long pages? Our solution was simple: give them the choice.

Only the information you need based on the kind of work you’re doing.

If you’re a designer, everything you need is on the Design side. We’ll give you the RGB values for colors, the ability to interact with the components in different contexts, and guidelines for using it in your interface.

When you’re ready to develop, switch to the Code side for a dev-friendly dark mode. Grab variables, copy a code snippet and learn all the component’s props.

Real-world code snippets that update based on the platform you’re working on.

We even have things split up by Platform, so you only see exactly what you need.

To make things easy, we save both your role and platform as you navigate through the site. If you’re an iOS developer, you don’t have to switch to the Code side and select iOS over and over again — do it once and it remembers for every other page.

We spent a lot of time considering this “focus” mode, ultimately embedding the user in the content by making things contextual to the task at hand. Putting this emphasis on their roles and making it feel tailored to them makes it easier and more enjoyable to use.

Make the Right Thing Easy

Above all, we knew we had to make things simple. The easier a thing is, the more likely people will use it. We had to go the extra mile beyond just making it contextual to making it truly easy-to-use.

To start, that meant making it easy for newcomers. Our Get Started guides provide the least amount of steps needed to begin using Uniform.

“The least amount of steps with the most amount of pictures” was the piece of feedback we clung to as we wrote our Get Started guides.

For our designers, that means giving easy-to-follow guidelines on usage. This can be anything from progressive disclosure on the variations of a button, to clear Do’s and Don’ts when dropping in something like a toast.

For both designers and devs, our research showed they want to direct other teammembers to places easily which is why just about every header on the site has a Copy URL function. Want to show your dev why you’re using a large modal over regular? Boom! The routing of the URL even supports that bit of collaboration by correctly appending /design or /code to the end depending on their selected role.

Small details like this make collaboration easy — teammembers can point each other right where they need to go.

What’s Next?

Initial feedback has been great, but our plan is to maintain the site with more updates and feature improvements than we had in the past. We look forward to hearing from our users on what could make it useful to them. We also plan to run our survey again to get an idea of how much we’ve moved the needle. Constant feedback and iteration is the best way to make sure we hit all the right notes with our users, so look for more updates soon. Oh, and before we forget — we’re hiring!