There are many ways you can create and document a design system, and none of them are inherently wrong if they help you do good work. It’s also natural to reach for the tools or processes you’re most familiar with when looking for a solution. Maybe you just have a UI Kit, or perhaps you have a component library coded up – these might be the aspects of design systems that you’ve started with or that meet your needs – but documenting what you have and how to use it is an important factor. This empowers others to know how to use the elements you have and easily integrate them into their work.

The scope of your design system may vary. If it lives purely within your design tool, having guidance may make sense on the surface, but ultimately it’s not just for designers, it’s for those taking it to the next stage and implementing it in code. Similarly, if you’re starting from code, there may be details around implementation that feel right alongside it, in the form of a README or similar but are developers the only audience for this content?

Know your audience

Whether you start from a team or organization weighted towards either design or development, it’s worth being clear on who the prospective audience for your design system is. As design systems grow and mature, the documentation often attempts to be increasingly inclusive across disciplines and teams. It may be fine in the short term, but it’s worth looking ahead a little – what might be a viable solution to ensure your system works for everyone?

In an ideal world, your collection of components would almost be a catalog of solved problems, so being able to clearly articulate what problem they solve (their purpose) and what use cases they have (their intent) should talk to your whole audience. You could then dive deeper into implementation details for designers and developers and incorporate input from researchers and content designers. It might not be a problem space you can fully address at the beginning of your journey, but an awareness that the short and long-term audiences might be different is helpful to feed into your roadmap.

Reducing friction and the barrier to entry

What may work in the short term can often put friction in the way of having others contribute. Within a design tool, developers might understandably see what’s in your library’s content as the designers’ domain. While they may feel capable of editing and amending, do they have permission? Is this encouraged? Does doing so mean that more people need to be editors or have some form of higher privileges in that tool?

The inverse creates more obvious friction. There are great tools out there, like Storybook, to enable developers to document components and be interactive in the browser. If your audience includes less-technical or non-technical people, some processes or workflows can make contributions more difficult. You have a number of solutions that might help to alleviate this, from training people to use Git/version control and Markdown or basic JavaScript to using a staging area for docs changes in another text-based tool. This creates a high barrier of entry for non-developers to feel like they can participate in the design system. Though a Storybook plug-in (for example) might show your whole Figma file next to a coded component, there’s an inherent disconnect between them.

Going to the source

In an ideal scenario, any given component would have a home that transcends the methods of implementation and bring the problem space and execution closer together. Over time, this becomes the focal point for anything design system related, which could go so far as brand in one direction and technical details or testing methods and pipelines in the other. Much as data has been recognized by many organizations as a vital asset, so too can a mature design system.

Having documentation surfaced in a way that isn’t tied to one domain and is accessible to everyone allows it to become the source for the design system; the one place you should go to know what the design system contains and how to use the elements it contains.

Scaling

Attempting to second-guess tomorrow’s problems and prematurely scale any solution can lead to over-engineering, but this feels a little different. Giving your design system documentation early attention for a wider audience actually becomes part of the suite of things you can try to aid adoption, contribution, and foster community. Reducing friction and creating a lower barrier of entry not only is an enabling factor to all of these positive factors, but it does also allow your system to scale.

What may start as a simple initiative within a discipline may, if successful, become something the organization depends on from many disciplines. In this sense, scaling doesn’t mean coping with thousands of viewers or even many editors but having the space and the tooling to enable the more human elements of design systems.

So what makes a good place for documentation?

Some of what good documentation can provide is both confidence and consistency, as much as it’s about flexibility and change. The way that you document can be a large part of that. Embedding it in a tool or alongside your code is an important first step, but it can’t scale – it’s inherently quite exclusionary. It serves a subset of the potential contributors and audience, either those on the design or development sides of your organization.

Whatever you choose, being clear on who this is really for and what they need from it has to be at its core. Successful docs help empower people to do great work, which is what its all about!

When docs with your code can work

• Your audience is other developers or those with technical skills
• The wider community around the code it comfortable using the format(s) and processes you have
• Consider the relationship with designers and non-technical people to ensure the relationship between problem space, through solution works for everyone

When docs with your design can work

• Your audience is predominantly other designers
• You have sufficient seats/access for everyone that will need it to your design tool
• Your audience is happy that they can learn everything they need from it
• In some way, there’s a link with code execution(s)

When documenting elsewhere can work

Obviously we’re biased here (zeroheight being a documentation tool) but whatever you use, there are reasons why using something not tied to either design or code can be the best solution:

• There’s a single URL for everyone for the design system
• Becomes the source for everyone around the design system; both the DS team and the wider community around it
• The way that docs are written should be across disciplines
• Contribution can have less friction, so helping more people feel included