Writing for Design Systems
By: Hunter Nielsen
Tags: Documentation, Ux Writing, User Experience, UX, Design Systems

You may find yourself having to make some tradeoffs as you navigate this journey, including difficult decisions about audience prioritization. In an ideal world, design system documentation should appeal to a wide audience that includes both developers and designers. Each of these groups will come to a design system with different requirements and expectations. Developers may be looking for detailed documentation on code usage and implementation. Designers, on the other hand, will need guidance on when to use a component, best practices for working with UI elements, and guidelines that address visuals, interaction, and content. For the time being, we provide a link within each spec that directs users to the relevant page in Storybook. Once there, developers can pull the metadata they need to add to their code. The ultimate goal is to embed a Storybook tab within each component spec so that users don’t have to go to a separate site for things like code and API docs. In addition to reducing friction, this will have the added benefit of ensuring that taxonomies do not diverge. It’s up to each organization how they want to blend design and code. Choose the solution that works for you but be cognizant of the risks/rewards and how these may impact your design system long-term.

Design systems are constantly evolving and are never really “finished.” They change as a company’s customers, markets, demographics, solutions and services shift and change. Jutro is more than just a UI kit or a pattern library. It represents all of the different ways that Guidewire communicates and interacts with its users. Design system documentation plays an integral role in that conversation, articulating Guidewire’s design philosophy and point of view on content creation. We’re proud that Jutro has reached a level of maturity where we can release it to our customers, and we continue to plan for the future. The team is focused on building out our business pattern library to account for common use cases within the P&C space. Moreover, we want to capitalize on the content and writing guidance that we offer for common interaction components by providing reusable and repeatable content patterns. These will help our designers to work faster and with more confidence, and users will benefit from greater consistency and clarity in our copy. This list of initiatives is by no means exhaustive and I’m sure we will continue to add to it as new opportunities present themselves.

Creating a design system from scratch is a major undertaking. It requires buy-in and contributions from many stakeholders and a commitment to maintaining and evolving that system. It’s not a sustainable model to have one person responsible for the entire project. Diverse perspectives are essential to producing a living, breathing design system that is successful in the long-term. Guidewire has a core team that is working on Jutro. We meet regularly to discuss where the design system is headed and plot future updates. Overtime, I could see this team model expanding to include contributions from others within the organization, including subject matter experts. It’s been a rewarding experience watching our own design system take shape, and I encourage others who are interested in this type of work to volunteer their talents. Design system teams thrive on interdisciplinary collaboration. The one thing that we all have in common: intellectual curiosity and a willingness to learn.