Design system projects often begin from the style — colors, fonts, and more are informed by brand values or existing artifacts. Following paradigms like atomic design, the core team then puts together components. Soon, the rollout happens and teams start wanting to use it. Now there is a need for design system documentation. Without good documentation, other teams will have to rely on the core team for support. While there are documentation solutions, configuring and getting them off the ground can be time-consuming and daunting. Instead, consider developing documentation incrementally that meets the needs today, while preparing the road for tomorrow.
Bringing in a solution can be an exercise in trial and error. New tools ask the team to commit to building familiarity. Design system documentation doesn’t need to be overly complex. Especially early on. Leverage existing tools and services available to the team.
While building out early concepts, start putting documentation into the design. Usually, all you need is to allocate space to hold notes. This serves as a handy reference and eases the workload with governance early on. It also builds the practice of documenting and working towards a common schema across styles and components.
What are some tools or services used by the organization to document or store content? Project wikis, like Confluence and SharePoint, could serve as the first writing board. As a bonus, these tools often facilitate sharing and authorization for team members. In active and well-maintained wikis, the design system will have findability and discoverability.
But without maintenance, the documentation can become obsolete fast. This can lead to confusion between teams and diverging application of design system standards.
As the design system grows, contributors — often from different roles — will come onto the project. Early on is the right time to experiment with what works. As development becomes more invested, the team will want to try developer-friendly tools such as Storybook.
Design system documentation is a balancing act of creators and consumers. Getting the right tools and workflows in place is critical to adoption. Starting out, use the flexibility to trial and experiment to see what works. But don’t overwhelm yourself and the team with too many options. At a certain point, the design system should reach a maturity level that allows the documentation to do so. Whether you decide to use open source tools, hosted services or even create your own platform, the lessons early on will provide guidance.
At Digitalist, we’ve helped clients build and maintain design systems. We’ve continually developed our best practices by working with a wide range of industries. Documentation is also an important piece of our handoff process. We want to ensure that clients and their teams can continue to work and maintain the design systems we build.
Sign up below, and thanks for reading!
We’ll be discussing how to manage divergence in design systems. Sometimes, even with governance and constant upkeep, a component ends up diverging from the design system. Letting teams extend and expand the design system doesn't need to be a balancing act. And it should not slow progress. Sign up for upcoming Design System articles!
