Design systems help create a shared language within an organization, but without good documentation, no one will be able to speak that language.
Without documentation surrounding each component, pattern, and principle, we start to lose the standards we worked so hard to create in the system. Our unified tone of voice can slowly disappear, we lose team buy-in, and we end up in the same boat as before we created the design system.
The trickiest part of crafting design system documentation is that it cannot be created by one person, working in one discipline. Documentation needs to be able to speak to all design system users: designers, developers, product managers, marketers, etc. And the best way to speak to all of those different audiences is to have each of them participate in writing the documentation.
Great design is the iteration of good design
How Do You Start?
A helpful mindset to have when working within a design system is “Great design is the iteration of good design.” This does not just apply to the design discipline, but to every piece of a design system. It is ever-changing, ever-expanding, and it will get more complicated as we add and build. This is why having a firm foundation to start from can be extremely helpful.
Here are a few things that can help create a good starting point:
Defining a shared workspace
Sharing terminology defined within a glossary
Establishing content templates for common pages and content blocks
Creating an auditing and review system
Defining a Shared Workspace
A shared and collaborative workspace helps tremendously with crafting design system documentation. In the past, we have found platforms like Google Docs, One Drive, and Confluence to be helpful. These platforms allow for multiple people to write, edit, suggest, and review the same content at the same time. These platforms also help us create a folder structure that can replicate our sitemap, allowing for easy findability of specific content while being able to house the entirety of our documentation in one location.
Glossary
Shared terminology within a design system team builds a common understanding of assets and how they’re used. It reduces confusion when working across disciplines and helps the team communicate more clearly with consumers of the system.
Creating a glossary for documentation authors can guide consistent language, establish naming conventions for components and assets, and foster collaboration and shared understanding among all stakeholders involved in the design system.
Here are a few tips on starting your glossary:
Start small, and allow the glossary to grow with your design system
Use plain language, and avoid circular definitions. For example, instead of defining “component” as a “reusable component,” you could define it as “A reusable piece of UI”
Define things with cross-discipline users in mind
Explain your naming conventions and standards, an example is explaining the difference between a “primary” and “default” component
Templates
Page templates are an excellent way to create consistency within documentation. A template can be created for common page types like foundational pages, component pages, and pattern pages or for common content blocks like overview sections, or additional resource sections. Templates can be formatted to best fit the needs of the writer. Guidelines around images or code blocks can be included, and it can be helpful to color code what text is consistent page to page, what text needs to be edited, and what pieces are optional.
Review Process
Governance models are important to figure out early on. Who has final approval, who owns what piece, and how do we ensure the project keeps moving forward? Nailing down a review flow can help guide the governance conversations.
Using a project management software can be extremely helpful when crafting documentation for a design system. Treat this like any other project. A project management board can help all these moving pieces feel easier to follow. A step can be created to represent each piece of the review process. Swim lanes can be created to represent which discipline is working on the documentation at what time. Regular standups can help everyone feel involved and understand how everything is coming together. A lot of documentation goes into a design system, and with so many cooks in the kitchen, it’s important to track this work thoroughly.
Who Should Write Documentation?
When curating design system content, it can be very helpful to have set roles. In our experience, it’s helpful to have writers who work within the space they are writing about. If we take a look at a documentation site component page for example, we can see how this would apply to real content.
Component Overview Section – This can be written by a product owner, designer or developer.
Usage and Behaviors – This can be written by a designer.
Code Guidelines – This can be written by a developer.
Accessibility – This can be written by an accessibility expert.
Content Guidelines – This can be written by a content specialist or product owner.
After an initial draft is created, a reviewer from the same area of expertise should help ensure the documentation is providing clear guidelines. This is a good time to find holes within the documentation that could cause confusion for the end user. Next, a reviewer from a separate discipline can help ensure alignment and understanding across the design system team.
After all initial edits have been made, it is helpful to have one person who is responsible for final review and polish of all documentation. This role is often a product owner or content specialist who can help align tone and language across all sections.
The Benefits of Collaborative Documentation
Breaking out of the silo with design system documentation can provide huge benefits, such as:
Higher accuracy and technical depth
Improved clarity for all audiences
Faster onboarding
More buy-in and ownership
Higher quality through iteration
Cross-disciplinary learning
Designers can ensure the documentation includes important visual and UX guidelines while learning how their choices impact development’s workload. Developers can verify technical feasibility and identify reusable patterns while learning about how prioritizing the end user experience can dictate a design. Content strategists improve clarity, structure and tone while gaining a deeper understanding of how UI changes can create accessibility.
By involving each team in the creation of the design system documentation, you are increasing the input, iteration, and refinement of each piece of content. You can increase design system adoption by allowing the team to feel ownership of the system, which lowers the risk of documentation falling out of date. You are building a shared understanding by learning and growing together, and the documentation becomes an integral part of alignment instead of an afterthought.
