Design systems in government: Improving documentation for better collaboration

In this post, we’re going to provide some guidance on building or maintaining the documentation for design systems, but many of these concepts could easily apply to other types of projects. Our Design Systems Working Group conducted multiple research sessions with the Ad Hoc team to better understand the ecosystem of design systems we create, maintain, and use — and the pain points around that work. Documentation was one of the themes that came up over and over again. We decided to try and distill that feedback into some general recommendations.

Make the documentation consistent and predictable

Clear, concise, and predictable documentation will help users of the system understand what it was designed for and what it wasn’t. Whether you’re building new documentation from scratch, or are trying to improve existing documentation, a good place to start is to define what types of documentation you want to provide.

Your documentation could contain:

• Basic description of the component
• Instruction on how to modify styles of the component
• Guidelines for when to use the component
• Guidelines for when to consider alternatives
• Additional resources
• Accessibility considerations

Having a clear definition of what type of documentation the system will provide helps with the creation and validation of components. In addition, this definition can serve as a guide for when a new component has enough documentation to be considered “complete” and released into the system. “Complete” is a loaded term here because documentation, just like the overall design system, is a living source of truth that is subject to change based on technology changes and new information.

Inconsistencies in documentation can lead to confusion, wasted time, and unnecessary work. Having some sort of outline for the overall documentation, as well as the specific sections, will help ensure that your documentation stays consistent as the underlying product grows or evolves.

Consider adding context to your documentation

Most documentation tells you what something is or does and how to use it. When we’re using design systems to build complex products, it’s useful to go just a bit further by adding context to documentation.

Let’s think about a button component as an example. Most design systems will have multiple button components. If one of the goals of a design system is to ensure consistency across a project, then it’s not enough to simply say “This is a button component and this is how you use it.” You need some sort of explanation for how you intend the various buttons to be used.

The amount of guidance you give users needs to be balanced with the amount of freedom that you want for consumers of your design system. So, as you’re building or improving the documentation of an existing system, it can be helpful to determine what elements need the most guidance to ensure consistency and what elements are more open to a variety of use cases.

Lastly, adherence with best-practices and user research are often integral parts of building components and patterns for design systems. But so often users don’t know how you made decisions during the construction of the system. If you chose a particular semantic structure for a modal component to ensure it’s fully accessible for users with screen readers, having a sentence or two explaining that structure might be incredibly beneficial. Not only would it ensure that users don’t feel compelled to alter the structure, but it could also educate the users and communicate user research and inclusive design as underlying priorities of the project.

Your documentation can’t do everything — and that’s OK

It’s important to note that it’s impossible to have documentation for every situation where someone might use a component. Adding context and guidance to documentation is a great way to improve a user’s understanding of a system, but you can’t account for every use case — and that’s OK!

For example, let’s say someone places an image inside a form and your documentation doesn’t account for this type of situation and how to handle it. No sweat! However, if all of your users are placing images in forms, then your design system should have information around this type of interaction.

As with any project, you’ll simply have to define those priorities as clearly as possible and then build from there. The better you understand who is using your system and what they’re using it for, the better decisions you’ll be able to make about how your system is organized and how to prioritize that in your documentation. Conducting periodic user research sessions is essential to maintaining the health of any design system. Are your users finding what they need, both in the system and the documentation itself? Are your users using the design system in a way you didn’t intend? Could updating the documentation fix that?

The work is never done

There will always need to be additions, revisions, and additional work to keep your documentation up to date. The most important thing to consider is ensuring that your team has built in time to work on documentation. If that time is not defined in some sort of cadence, the documentation will likely stagnate with the other responsibilities of building and maintaining a project. But if collecting user feedback and keeping the documentation up to date is built into the rhythm of your project, it will help ensure that the project stays healthy and the team (hopefully) stays happy.

Read the rest of the Design Systems in Government series: Less can be more, Communication is critical, and When to start.