Should you customize your design system documentation platform?

Whatever tool you’re using to document your design system, you’re probably considering your customization needs at some point. Different layouts, color options, information architecture flexibility… It’s a legitimate need to structure your design system and align this platform with your brand identity. However, when is customization too much?
There is an urban legend about Henry Ford’s quote saying: “If I had asked people what they wanted, they would have said faster horses” that makes me wonder if a fully customizable documentation platform is really what you need for your design system. There is no doubt it is important to have some flexibility for your documentation system. But beware of wanting too much flexibility, otherwise, you may lose yourself in the details at the expense of the essentials.

Before you embark on fully customizing your documentation, here are some important questions to ask.

Does your audience need fully-branded documentation?

Maybe that’s the first and most important question you should ask yourself.
Of course, having a documentation platform that is aligned with your brand makes sense. Users of your system should feel they’re at your brand when using your documentation platform. Most of the time, the reasons why you need to customize your documentation are all about the brand and outward appearance of your organization. In the end, your brand’s identity and principles should be reflected in your design system; or should they?

Who is asking for customization?

It is not uncommon for a design system to become political, representing different stakes for different people or teams within a company: business stakes, brand stakes, visibility stakes, etc. In light of this, it’s not surprising that the design system has to be customized so it better fits the company’s image and, above all, it better fits the strategic interests of every stake.
So maybe you should wonder: could there be a certain pressure coming from the brand, the communication or the marketing department? Is it possible for your documentation platform to become biased, serving the interests of several members and teams, possibly to the detriment of your design system itself?

Do they need to be fully or partially branded?

The degree of customization also needs to be understood: how does your documentation need to be aligned with your brand? Does it simply require your logo, a few colors, and, perhaps, the right font to reflect the main characteristics of your visual identity? Or are there more pressing needs that require a change in layout, fine spacing management, specific iconography, shading, radius, or even motion?
Ultimately, this is merely a documentation platform for your design system. The goal is mainly to provide resources to teams to help them work more efficiently. In this context, is it necessary to emphasize the brand image so much?

Can you do it better than third-party solutions?

Creating your own customized solution can have many benefits, both in terms of customization and independence. However, a home-made solution can quickly represent a huge investment in terms of time, resources, and energy. Is it really worth the money and effort? Being independent from a tool shift the problem to being dependent on other resources, especially human resources. Would you rather train your people on a third-party solution or hire new staff to maintain your system?

Do you have the resources to build and maintain your custom documentation?

Having a fully customizable platform can be very time-consuming as it will add many maintenance costs and cognitive overhead to get the right level of customization for your platform. These costs and efforts could probably be spent on bigger problems such as documentation, content architecture, process and communication, or even component creation and maintenance. Having your brand applied on your documentation platform is necessary, but how much customization do you really need, and at what cost? Additionally, a fully customized solution will most certainly require the help of a dedicated team to maintain it over time. Can you afford to be so dependent on these people for the success of your platform? What happens the day they leave the team?

Why rely on a third-party solution?

Choosing a third-party tool for your design system will relieve you of various obvious issues, including deployment costs, maintenance, and back-office concerns. There are, however, other benefits that may not be immediately apparent at first glance. The solutions provided by these third parties have already encountered many problems, so they are well-designed regarding layouts, templates, tool synchronization, etc. Therefore, using these third-party solutions saves time by not wasting hours on finding the most efficient way to structure your content or thinking about the right layout for your documentation. These solutions have already been considered for you.

A good example is Mailchimp. It is one of the most popular solutions for generating email templates. While this solution is great for helping you send out newsletters to your users, it is not its main strength. By using a service like Mailchimp, you can build the right layout and get the right advice for your emails, analyze the data, avoid errors (spam, broken images…), and increase engagement, among other things. Things that could often fall by the wayside if you were building the solution yourself. They have the time, resources and, most of all, the motivation to build the best possible solution for this problem. If they don’t, their business dies.

It is, above all, an undeniable asset that will enable you not only to generate emails, but also offer all the expertise, knowledge, and experience needed to ensure your emails have the greatest impact, even if only because they have the dedicated resource and access to data because lots of people use their platform to send mail!.

Last but not least, relying on a third-party solution allows you to focus on other more relevant aspects, such as content and process, rather than worry about these solutions, since they are generally reliable.

Does your customization provide value?

I think it’s natural when you work on your design system to have something on brand, especially for designers. Additionally, it is pertinent to consider why there is such an interest in and need for customization. The reason could come from observing how many tools allow customization (WhatsApp, Google Chrome, Messenger…). However, do not customize for the sake of customizing. While it makes sense to customize the experience with these tools, when it comes to documentation tools, it’s more pertinent to focus on clarity and efficiency than customized options.

Isn’t it all about content, after all?

Keep in mind that this documentation system is primarily for the content, so how this content is articulated matters more than how it looks. The more time you spend on customizing, the less time you have maintaining your design system.
Besides, it is not surprising to see some brands comply with these restrictions when it comes to using other content solutions without asking for specific customization options. Whether it’s the ready-to-use email templates of Mailchimp, Instagram’s grid or even the Wikipedia pages, brands adapt to each platform’s layout and constraints. Why isn’t it a problem with these very strict and restrictive platforms and why do people argue so much about customization for documentation platforms?

Will customizing mean you don’t have time to focus on the fun bits?

Constraints lead to creativity. However, if these platforms can be restrictive, it doesn’t prevent brands to finds ways to add some customization to stand out. Hacking the Instagram grid, matching the avatar and the banner on social media, customizing email templates… Brands know how to play with the constraints in the end. If it’s OK to comply with these tools you rely on for your brand, why would it be different for your design system documentation platform?
See what Decathlon or Brainly did with their design system using zeroheight, for instance. They succeeded in articulating content and finding creative solutions to represent their visual identity in the best possible way.

Are you solving your core user problems?

The purpose of a design system is primarily to make it easier for your teams to work together more efficiently. The setup of a design system platform is one of the essential steps for providing your team with the documentation they need to work on their projects.
So, what are you trying to achieve with a documentation platform? It’s all about providing your core users with content that is clear, concise, easy to comprehend, and easy to use. Your focus should be on solving that problem. Are you really focusing on your core user problem when you’re searching for customization options?

How different is your documentation platform going to be from the other ones?

The design system landscape shows how many different tools and solutions are used to build these documentation platforms, yet in the end, these design systems all appear identical. Left navigation, header, sidebar for the sub-navigation, component anatomy, tabs, code snippets… it’s very common to find the same structure, the same layout and the same way to display documentation. Styles may change to represent the design system brand (colors, fonts, logo, iconography…) but in the end, there’s no need to reinvent the wheel when it comes to building a documentation platform.
So, once again, here’s the question you should ask yourself: are you really going to be customizing, or just doing it the same way everyone else has?

How good is your design system adoption?

Today, content, usability, and accessibility should be foundational priorities when creating your documentation. Increasingly, digital products are becoming more uniform to ensure compliance with current standards, which is accelerated by design systems. Consequently, it is not surprising that these design systems run on uniform platforms. It does not make sense to recreate the documentation experience when we already know the crucial structuring elements of a useful and efficient system. In other words, what’s essential is to customize this platform to suit your brand’s identity rather than letting the brand build this platform.

Lastly, let’s not lose sight of what these platforms are for: documentation. Your design system users might view this platform as the burdensome with all the customizations and refinements available. The success of an effective design system depends largely on adoption, and simplicity plays a significant role in adoption. As a result, if it no longer facilitates maintenance and easy use for all teams, so haven’t we lost our original purpose?

Find the right balance

It goes without saying that a design system should reflect the visual identity of its products and the company. Still, it’s all about finding the right balance between keeping the platform simple and maintaining the right level of brand identity.
This means that adding a logo, customizing colors, fonts, and having a landing page or a custom domain name are the kinds of essential things you can expect for your design system documentation.
However, the maintenance of this platform shouldn’t add layers of complexity to an already complex design system. That’s why features like custom CSS, custom documentation widgets or custom templates might be interesting at first sight, but will definitely bring more complexity to your design system and might not be worth it. Following this path may even put your design system at risk for long-term development. Teams occasionally have someone interested in CSS customizations. However, if they are the only one capable of doing it, who will maintain it when they leave the team?
Keep in mind that the more you add to your system, the more likely you are to lose simplicity and therefore adoption for your design system.
As you customize your documentation platform, ask yourself: “am I wasting my time?” or “is there something other aspect of the design system or documentation site that needs my attention more?”

If you haven’t seen it yet, we just released a bunch of new features to help you take your platform customization to the next level within a healthly balance: add a hero image anywhere, change the size of shortcut tiles, add a link to an image and much more. Check out our blogpost about the 9 new ways to customize your design system with zeroheight to learn more.

We’re also very curious about whether your documentation should be highly customizable or not. Get in touch with us on zheroes, our zeroheight Slack community, and share your thoughts on this topic!