Here’s why you need a design system documentation site
Creating a design system documentation site can be a challenging but rewarding process, especially when you work for an organisation with many teams and products.
Design systems are an essential tool for organisations to maintain brand consistency, improve efficiency, and facilitate collaboration across product teams. But in order to achieve these aims, first we have to think about how we can easily share this information and keep it up to date. That’s where documentation sites come in.
In this post, I will share some of the benefits we’ve achieved by publishing the first release of our documentation site at JustEatTakeaway.com.
Maintaining consistency
When designing a documentation site for a design system, maintaining consistency across all pages is crucial for providing users with a seamless browsing experience. This can be a challenging task, especially when multiple team members are involved in the design process over an extended period of time.
Creating a cohesive design language and a layout that users can navigate is essential to ensure consistency. For example, when new content or features for the design system are requested, it’s important to refer back to the design guidelines that encompass the visual elements, such as colours, typography, iconography, and visual styles, which will be used throughout to ensure consistency is kept.
Creating layout guides is also useful to ensure that any changes align with the overall design of the documentation site. When you do that, try to come up with templates or grids that define the arrangement of elements on different screens or pages. This will contribute to the consistency of the design across the documentation site.
Another thing to keep in mind is that in order to maintain consistency, it’s necessary to apply changes with caution and be aware of the potential consequences of even small alterations to the site’s visual look and feel. However, by being meticulous in this approach, a documentation site can provide a reliable and consistent resource for users seeking information on a design system.
Organising documentation
Another key benefit of designing a documentation site is the ability to organise content in a logical and intuitive manner, making it easy for users to find what they need. However, organising content can be a significant challenge, especially when different stakeholders have varying opinions on how information should be structured.
To address this challenge, involving all stakeholders in the planning and development process is crucial. This approach ensures that the needs of different user groups are considered and that everyone has a voice in the information architecture and content strategy definition phases.
User research is very helpful when trying to understand the needs of different user groups. In our case, we spoke to multiple stakeholders and potential users of the site to figure out what would be their expectations for the site and what contents they would like to find in it. We also carried out story mapping exercises taking into account the learnings from the research, which helped us plan the work and think about a fitting information architecture strategy for the documentation site.
Despite the potential for challenges and delays, involving stakeholders in the process ultimately leads to a better documentation site that meets the needs of all users. By carefully planning and paying special attention to information architecture, a documentation site can provide a clear and organised resource for designers, developers, and other team members to reference when working with a design system.
Bridging the gap between designers and developers
Another key advantage of a documentation site is its ability to act as a bridge between designers and developers, ensuring that both groups can access the information they need to work with the design system effectively. This is particularly important given that designers and developers may have different levels of familiarity with each other’s discipline.
By providing clear and concise explanations of technical terms, the documentation site can help designers better understand coding concepts and terminology. Similarly, providing enough context and examples can help developers understand how the design system will be used by designers in products, which can increase the efficiency of the development process.
Involving both designers and developers in the site development process can also help to ensure that it meets the needs of both groups equally. By soliciting feedback from designers on the clarity and usability of the documentation, and from developers on the technical accuracy of the documentation, the documentation site can be refined to be an effective resource for both groups. Ultimately, this can lead to a more efficient and collaborative design and development process.
Balancing detail and brevity
The last benefit I want to talk about in this article is the ability to provide concise and useful information to users. Using the documentation site, we can ensure that the documentation we put out there for our users is clear and easy to navigate, which is crucial for encouraging user adoption and preventing frustration.
To achieve this, I drew inspiration from a set of principles I learnt during Amy Hupe’s Design Systems Documentation Course. These include:
- Using clear and concise language
- Prioritising the most important information and making it easy to find
- Using examples and visuals where possible to help illustrate concepts
- Using a consistent structure and formatting throughout the documentation
- Adding links to provide additional information, instead of trying to explain it all on the spot
By following these principles, I was able to create documentation that strikes the right balance between detail and brevity, making it easier for users to find the information they need without feeling overwhelmed. This in turn contributed to the success of the design system and increased user adoption, which we have seen reflected as a +5 point increase in our net promoter score (NPS) compared to three months ago before we released the documentation site.
So, what are the learnings?
As I stated right at the beginning of this post, creating a documentation site for a design system is no easy feat. It requires careful planning, collaboration, and attention to detail to ensure that the site meets the needs of all stakeholders.
One important thing I kept in my mind while designing the site was to remind myself to stay focused on the end goal: creating a documentation site that enhances the productivity and creativity of all those who use it, acting as a global source of truth for all digital products at Just Eat Takeaway.com.
By staying true to this statement and our design principles, and by working closely with my developer counterparts, colleagues and stakeholders, I managed to design a site I’m proud of, which is beneficial for Just Eat Takeaway.com at multiple levels. I hope that my experience can inspire you while/as you embark on this journey.
–
Shoutout to Jamie Maguire for the work you’ve done to make this happen & special thanks to Molly Nye for the awesome illustrations!
