A complete design system is the backbone of a digital product, especially at enterprise organizations. Design systems are needed by design and development teams to create cohesive products and scale without hitting design details. However, organizations aren’t sure how to implement a design system, with teams creating one-off solutions rather than focusing on a unified experience.
Design systems do not exist in isolation. They are a key part of any modern product ecosystem and the role they play ranges from enabler to investment target. One important consideration factors in when defining design system documentation best practices is the scope of work. This articles features practical advice on how to use working examples as a tool for defining design documentation processes associated with real world implementation requirements, including industry best practice for deriving designs and rules from customer needs and product requirements.
Design documents are really the heart of creating a great software design system. These documents are an essential tool that is used across all levels in your company: from clients to executives, and all the way down to the coding team. Design documents explain why and how decisions were made when it comes to the designs created by the designers.
Design system documentation is a new concept that marketing teams have started adopting. The purpose of designing a system that prevents inconsistencies and duplications and an overall more streamlined, efficient workflow. In other words, the idea of design systems is to provide designers with guidelines and rules, so they can improve the way their designs are perceived. In this article, we’ll explore best practices for design system documentation.
How about documenting those?
One of the pillars of any design system is undoubtedly its documentation, otherwise you would simply end up with a component library, and we all know a design system is much more than that. The design system’s documentation is key for its adoption. The product team will only be able to use it properly if it’s well understood, which defines its success and longevity. Furthermore, a good documentation can also facilitate scalability and improvements.
In the process of documenting your design system you will need to write about the Design Tokens, the Content Design definitions of your brand as well as the Components themselves (both in code and in the UI Kits), along side the rules for how and when to use them.
Here are a few good practices that any team can adopt that will make the process of documenting your design system much easier, resulting in a good read that your users will want to dive in:
Know your user
All good products start with understanding the users needs and wants. This is also true when we look at the documentation as a product to be consumed by others, like the colleagues outside of the design system team, for example. A crucial step for success is to have a clear picture of all the users of this documentation.
You can draw inspiration from some cleaver graphic designers out there. In the light of recent events (the pandemic) we have witnessed many approaches to get the social distancing message across to a large user base – namely the world’s entire population. The people at Berlin’s public transport tried this:
They could have just written 1.5 meters, instead they asked the question “What does 1.5 meters look like?” Resulting on a very relatable – and witty – explanation for the necessary distance: “1.5m is the same as three corgi”.
The example above is a good real-life case of how Design System teams could define their documentation. Ultimately, the documentation of your principles and components is not just for your Design System teams, it’s for the Design System’s users, hence the importance of considering just who is the user: who is using this design system? It’s not just designers and UI engineers or front-end developers. What other disciplines are using your documentation site? Do they have enough information? Do you have the context from their perspective?
At the start of a Design System, after building some components, the natural path is to think of the necessary documentation required to consume them, which information will help the users implement those components in the interface. This normally starts from the designer’s or developer’s perspective, but it shouldn’t stop there. Have you considered the other disciplines as well? Make sure your documentation doesn’t lack the perspective of all users who are going to be using your documentation.
The other side of this coin, the one in which you don’t take everyone’s point of view in consideration, is an ugly truth: your documentation will be left unread, your design system will become inconsistent due to poor understanding/implementation and overall frustration with what could’ve been the solution to a scalable and cohesive product. As once mentioned by Sarah Drasner: ‘The folks that bounced due to bad docs, tutorials, and onboarding aren’t telling you. They’re just leaving.’
It’s very important to focus on documentation from your users’ perspective.
Organise the information
Organising your design system’s documentation will require several parts coming together, shining a light on the need of proper information architecture to make it all understandable. A place to start architecting it can be by figuring out where the user is coming from.
When the designer lands on your documentation, he might have come from a link embedded in his assets library. The developer that is going through the Design System’s information, might have come directly from a link saved in his browser. In both of these scenarios they are probably already familiar with the system and just need to find specific information. It could be worth outlining the types of information the users would normally be seeking and how you can organise it in the most optimal way for that path.
It’s not just about making a list of components. The hierarchy needs to be considered. Identify the categories you have so that it is easier to navigate and easier to find out what the user is looking for. This is commonly achieved by a very clear navigation, often placed in a left panel, components in a clear section, as well as a “getting started page” for those arriving in it for the first time. It might be worth considering a different onboarding experience for the different types of disciplines, since the type of information they would be most interested in will most likely differ slightly. Let’s also not forget the power of a good search tool so the user can quickly find what they are looking for. This is usually well worth the investment.
Set a single source of truth
With different users in mind, and different people collaborating to an ever evolving design system, it’s easy to fall into the trap of misalignments and outdated information.
To avoid that it’s wise to decide early on what will be the single source of truth. You can have it start from design, where components made in Figma hold the main definitions, or it can start from development where the React components and its inline documentation will define the origin. There are tools that teams can use to further specify all the details of the components in stories and you might be even already riding the latest trend and have all your design tokens already agreed and placed in one json source.
Don’t forget to assign a person to keep this information up to date, wherever it originated. Small visual decisions can be made along the way when building the final product and the design system can assist in an impactful change if it has been set up correctly. However, when many disciplines are working on the same components but in completely separate softwares, like React and Figma, the design system team needs to make sure everything is in sync as well as where all the documentation is stored.
Take into account that setting up your design system also means investing in a good documentation website/platform, and with it comes maintenance costs. Luckily for us the more the design tools and development environments come together, start speaking similar languages, the more integrations we start seeing. There are a few options when trying to transfer important information from one tool to the other as well as a better understanding and use of design tokens that all tools reference as the single source of truth.
The content in the design system should span across all the different units or systems so that they are always in sync. You don’t necessarily have to define if design or code are the single source of truth as long as everyone is always interconnected and synchronising between definitions.
Write an introduction page
Often overlooked but extremely necessary for a strong buy-in of your design system is the ‘getting started’ documentation. An engaging onboarding can make or break your design system adoption, and you might want to consider different onboarding experiences for different users. It can be done as a step-by-step example, or one which is catering for the advanced users. Will your design system be started by a UI designer or a UI developer or a product manager? How do you onboard them? How do you prepare a getting started guide for it?
Some documentation websites already showcase a code sandbox on the getting started page. This can often mean Time for Value. As soon as you enter into the documentation site you see things in action and you don’t have to install anything on your computer. This practice can be seen in a lot of popular design systems which gives a taste of what it looks like.
Anyone joining the team and getting to experience the design system for the first time is a great resource to understand what is missing in the getting started flow. Present your design system to the new joiner, give them a task that involves using something from the design system and ask them to take notes of all the problems they had when they get stuck. What problems did they face? What was their action to solve it? Ask them to log whatever complaints they have straight away, so you can be sure they will bring you any new perspectives and problems they face as it arises. Then it is much easier to fix. If they leave it until they get used to it and have been working on it for some time, they might have forgotten what the problems were when starting to use the design system.
Define layout guidelines
Layout can be often neglected in documentation from a design system since it’s not an easy thing to turn into a component. Usually not enough guidance is given on how to consume the layout. The result is you have a design system, but the users of it ended up building a bad interface. They don’t know how to use a proper layouting solution to what was provided in the design system.
Consider having proper guidance and documentation for the possible layouts within your design system’s definitions. This can come as a flexbox solution, a grid solution, or a spacing solution. Having clarity on how to frame or to sketch out the layout for the interface is also important along with consumption of your design system components. Having better onboarding for layouting can really help to layout the interfaces in a better way.
Gather feedback
Take time to consider implementing some way to collect feedback from any of the design system’s users. It’s great to have a design system that works most of the time, but it’s also important to know when it doesn’t.
In some companies it’s only possible to acquire feedback through opening GitHub issues. This is a real problem for designers and non-technical people who want to give feedback to the design system, as even though there are templates for GitHub issues to make it easy to reproduce the issue and provide some insights, there are also other ways to get feedback for your design system.
A simple feedback box in the corner of the documentation website, where an email is provided and there’s space for the description of the issue, is one way to collect it quickly. Think about streamlining the process of giving feedback so that the user doesn’t (always) have to open a GitHub issue. Anyone who wants to provide positive or negative feedback can give it very quickly when it’s done through the documentation platform.
Take Google Cloud Docs Feedback as another example, you can very quickly give your feedback once you’ve read the document, you can review it, decide if you have any more issues and you can add information. Connecting that feedback loop with the design system’s documentation platform is a great way to keep listening to the feedback from your users.
Communicate early
For most people in your organisation, a design system is “just another tool” they have to work with, or in some cases, something they aim to ignore. This sentiment must of course be avoided, making it imperative to communicate early on how a good design system can contribute to your organisation.
There are several advantages of a design system, as Oscar Insurance Corporation notes, including:
- Scalability: Either it’s plain, old growth or breaking up a company into smaller pieces, scaling up or down can be a headache for any organisation. Using components and patterns in a wider or narrower context is, however, strongly alleviated by the use of a design system and will at least make your design team happier.
- Reuse: Instead of working double or unnecessarily starting from scratch on every new project, a design system allows your editors, designers, and developers to quickly reuse images, buttons, styling, and codes.
- Brand protection: Protecting the brand is an increasingly important priority for any organisation, as the brand is a quality marker and a fast-track for customers in their evaluation of your product. Having a central repository of definite brand rules in the form of a design system is another key advantage.
Be sure to make these advantages widely known in your organisation before venturing forth on the process of building a design system.
Conclusion
Software design documentation is one of the most important pieces of any software project. It’s a requirement for every digital project. The problem is that it’s not always easy to produce. There are best practices out there and I am going share them with you today.
Documentation for software design has its own set of best practices. But what about the documentation for design systems? It has those, too! In fact, there are some key differences with documentation for design systems that can help your team adapt and improve their workflow. It’s all about making sure to communicate effectively what will help users understand and use your design system. And you want those users to make informed choices throughout the process.