index

When Adoption Scales Faster Than You Can

Design systems aren’t just component libraries — they’re services. And like any service, their value depends entirely on how easily people can access, understand, and implement what you’re offering. As adoption of our design system grew we noticed our support overhead was scaling faster than we could.

Data from our survey validated what we were feeling, satisfaction scores on the systems ‘ease of use’ and ‘support & resources’ had dropped by 6% and 7% respectively. The problem wasn’t the components themselves, it was the infrastructure around them: our governance model, support practices, and most critically, our documentation. If we wanted to help teams scale up without constant hand-holding and reduce the time we were putting towards support, we needed to make some changes.

Auditing the Chaos

This wasn’t a surprise, we had been acutely aware of these gaps and had been adapting our processes to improve. We’d aligned on a protocol for triaging support requests and answering questions, and we scaled back our sprawling governance practices. The only thing left to address was documentation.

Our documentation was fragmented across three platforms: Figma for design specs, Storybook for developers, and SharePoint for everything else. Ironically, the design system had no single source of truth. Updating docs in one place often meant a need to update them elsewhere, inevitably leading to inconsistencies and conflicting guidance. Those gaps were eroding confidence in the system, and leading to growing documentation debt.

During this time I conducted a content inventory and audit for all of our documentation resources. This was slow, tedious work, but it was crucial to understand what we had documented, where it lived, and what kind of shape it was in. As part of this work, I developed a content scorecard to evaluate our docs against a set of criteria such as usage (views), accuracy, clarity, and visual examples, allowing me to rank the priority of future updates. It also gave me the context I needed to map out the information architecture for a new documentation site and create a plan for migrating our content.

Done vs. Perfect

With a clear understanding of the problem and data to support the need, I put together a proposal for how we could transform our documentation from a collection of disparate resources, into a unified source of truth. Allowing our team to drive adoption, reduce our support overhead, and enable closer collaboration across design and development. The pitch worked and we were given a green light and budget for a CMS solution (Zeroheight). With our resources secured, I needed to make a choice: perfect the content before migration, or move fast and migrate the content as-is. I chose the latter.

There were several reasons for this decision. For one, done is always better than perfect, because perfect never gets done. Simply unifying our documentation under one URL was an immediate win. We also wanted to showcase and justify the investment in Zeroheight to our stakeholders as soon as possible. And lastly, we wanted to avoid a scenario in which we were maintaining the old documentation resources, while trying to stand up the new documentation site.

A Framework for Success

With the migration completed and our new documentation site live, we could tackle the findings from the audit. Most notably, was a lack of consistency in how we documented our components. Some had robust documentation with plenty of examples, others were sparse and provided bare bones guidance, very few shared the same structure. It was clear we needed a standardized framework for how we documented our components. That way users knew what kind of guidance they could to expect from the design system. After consulting with my team to capture their input, I had a much better understanding of the needs across both design and development. With an audit of our docs, a prioritized backlog, and an agreed upon framework, we were ready to execute!

To accelerate the overhaul, I built an AI assisted tool that took a first pass at updating our docs. The tool took our existing docs and any notes (such as those from the audit) and rewrote them to match our new documentation template. It didn’t generate production ready docs, but it gave us massive head start that turned days (if not weeks) worth of work into hours. With a draft to work off of, we were able to move faster, and focus our efforts on reviewing, revising, and extending the documentation to meet our standards.

Now that it was time to execute I needed help from the entire team to bring this vision to life. No matter how you slice it, good documentation is hard to write and takes time (even if you’ve got a first draft to work off). More importantly, your documentation is a representation of your design systems point of view. Which can only be communicated by the collective expertise and knowledge spread across your team. What I’m saying is that if you want good documentation, then everyone needs to be contributing to it. When that happens, something special takes place. Documentation becomes a forcing function for your team to codify their thinking and point of view. Which in turn, improves our internal collaboration and communication, drives closer alignment across the team, and enables us to better serve our consumers.

The ROI of Good Infrastructure

At present we are still working through these updates, but we’ve made a ton of progress. Now we have a single source of truth, where anyone — regardless of their role — can learn about the design system and how to use it, and where design and development guidelines live side by side.

The investment appears to be paying off. Since starting our documentation overhaul efforts, we’ve seen a 16% decrease in support requests, and a 38% reduction in time spent resolving said requests. While correlation isn’t causation, the data suggests that our improved documentation resources are reducing our support overhead by driving self-service adoption and support. Lastly, it’s helping us prepare for what’s next. As our team explores meaningful ways to integrate AI into the design system, our documentation will be the foundation for training internal LLMs and agent-based workflows.

---