Where to start and how to approach it
One of the toughest parts of creating a design system might not be what you expect. Getting a design or development team to use it is generally straightforward; after all, who doesn’t want to make their job easier in the long run? Sure, the upfront cost might be high, but that’s an easy sell. No, the toughest part is the documentation.
Example of documentation contents page
It can be daunting if you’ve never done it before. Hell, I still find it daunting, even as someone who’s done it before, as when you look for examples and guidance on how to begin, you start to see the true scale of what you’re undertaking. Not only do you need to explain what every element you use does, but you also need to explain how it should and shouldn’t be used, all while standing on one leg and reciting Alphabet Aerobics. Okay… maybe not the last part, but you get my point. It can feel like a lot.
But don’t worry, I’m not here to spread doom and gloom. No, I want to take a look at what we can do to make this process less daunting and, ideally, a little enjoyable.
But before we begin
The fact you’re reading this means I can safely assume that you at least believe that documentation is vital for a design system to function. But before we delve into how we can approach writing this, you should know the documentation can be split into two parts:
Intangible: Your principles, what makes up your foundational thinking, and your ways of working that put those into action.Tangible: Your patterns, components, and usage guidelines. Alongside the tools that both designers & developers use.
I mention this as both are important when it comes to making your system work for you rather than against you. I’ll cover both of these areas, although I’ll mainly focus on how we document those tangible assets, at least in this post.
After all, those tangible assets cover everything from how we use colour to how inputs work and don’t work to even the space between the elements we place. Even just saying it like that might sound daunting to you, and that’s what we’re looking to change.
Example of introduction to a componen in documentation
Breaking things down.
So, how do we make it less daunting? By borrowing from Work Breakdown Structure (WBS). You’re likely familiar with this, as it’s the process of breaking projects into smaller, manageable pieces and templating those elements for easy reproducibility. As a framework, it goes a lot deeper, but the key steps we’re looking to borrow are the following:
Break It Down: Divide the task down into smaller, manageable parts. Start by listing out all of the pages you need to create and what needs to be included; this will create a self-contained task.Prioritise: Look for the parts causing the most friction/pain and begin with those. If that’s not easy, start with the parts that are frequently used or have dependencies.Track Your Progress: By doing the top two, you can do this. It’s easier to move through something when you can see you’re making progress, and it’ll help others see where you’re at.Review and Adjust: You’re not making a rigid plan. It should be dynamic and adjust to unexpected obstacles, priority changes or tasks.
How you do this is up to your personal preference. You may want to do it in Jira, on a Trello board, or even on a spreadsheet, but I like to do it as a Notion page, which you are free to look at and even copy. It’s just a generic template to help highlight the steps above and get you started.
I like using Notion because it doubles as a web-ready resource that is easy to maintain, share, and search, making it easier for others to access. But note that there are plenty of other tools for this.
Putting WBS into practice.
Not only can you use the WBS framework to break the back of your documentation, making it more manageable. But you can also apply it to each component page you create.
You may have noticed that I’ve mentioned a few times that our documentation needs to answer key questions, which is what usually makes it feel overwhelming. However, when you get down to it, these questions are consistent across every page, and we can use that to create a repeatable template that we can follow. Those questions are:
Example of breaking down what Options you have with a componet
What is this called, and what does it do?
These are the two most common questions users want to answer when viewing documentation, as names can change between design systems, and users need to know what options (see above image) and states (active, inactive, disabled, etc) are available for any given component.
Why should I use this?
As I’ve mentioned in a previous post, it’s essential to give clear direction on when one component should be used over another, as given the similarities between some components, it’s easy to think they can be used interchangeably. However, that’s rarely the case, and we should be explicit about this.
When should I use this?
I often think the why and when aren’t worth splitting out as they’re intrinsically linked. However, it’s still an important distinction as you need to build on the “why” we use something with a clear direction on “when”. As an example, a sidebar and modal can both be used to bring in additional context, which might be a similar “why”, but “when” we use each component could be very different.
How do I use this?
It’s possibly the most challenging question to tackle, or at least that’s how I feel. After all, here you’re trying to provide a list of options for a component’s usage alongside a list of do’s and don’ts, which is a broad topic.
I find it’s best to break these tasks down and approach them from two fronts—the first is by following the examples set by other design systems. You can use resources like The Component Gallery to find a specific component and review what others are doing.
The second is creating a spreadsheet, like the one the UI Collective put together, which helps you outline the options available for a component so you can see what you’re doing.
Example of component usage guidelines, with content taken from Adobe Spectrum
Something to keep in mind
When we break our tasks into manageable chunks, it becomes a little less daunting, and when we strip things down to the basics, it becomes easier to see commonalities across them. We can take things a step further and make it easier again by keeping the following in mind as we work through our design system, not just our documentation.
Remember you audience
It’s easy to lose sight of this one, as your documentation will be used by three very different personas: designers, developers and everyone else. Yeah, it’s a bit of a mixed bag, and by trying to create something for everyone, you can make something that is no good to anyone.
Your primary audience should always be designers and developers; you need to be able to show both parties how to use, when to use, and what to avoid. You should also be linking to code snippets or your storybook for developers so they can see the ins and outs.
Everyone else usually includes people like product managers, QA, researchers, etc. Those who might need to verify something specific but don’t necessarily need to understand the finer details. Nathan Curtis has written an excellent piece about these different personas and what’s important for them, so I recommend reading that if you want more details.
Steal like an artist.
We often get caught up in trying to make something unique when we should be embracing the influence of others and using it to learn, remixing and reimaging what has come before to build our own path. Austin Kleon has written a book by the same name, which delves into this mindset more.
However, the gist of it, and what I mean by this, is that you should constantly review and draw from existing systems as you build out your own. Use them as a roadmap to help you cover the use cases of a particular component or how something should work. You always use The Component Gallery to see how something works across multiple systems.
Forget about perfection
It’s all too easy to get caught up in making something that is ‘perfect.’ Especially as designers. However, we need to let go of this ever so slightly when it comes to creating documentation, at last, in the beginning.
Your documentation doesn’t need to look nice. It doesn’t even need to be complete. It needs to be functional. It doesn’t matter what form it takes, as it can be a string of Slack messages or emails; it just needs to be present and available for you and your team.
And that brings me to:
Maintaining your documentation and system
I did say that I would focus mainly on creating your documentation, but I also want to touch on some other points that could be of interest. After all, even once you’ve written and published that, as so many companies do, it’s an ongoing process to ensure they stay accurate and match your needs. You can employ a few activities to help you with this:
Design Critique: Don’t shy away from bringing new components or running through new documentation in your design critiques.Design Kick-offs: When starting a new project, assess and highlight whether an update to an existing component might be needed or if you need to create something new.User Research: You should always test your components; these are great times to get feedback, explore specific questions and assess accessibility.Design-Code Alignment: Before using a component, make sure you’re aligned across design, development, and documentation to ensure consistent usage.
You can run each of these in a few different ways, and what works will depend mostly on you and your organisation’s setup. Don’t be afraid to trail these and change how they work if they don’t meet your needs. It’s more important to do something that works for you rather than just going through the motions and getting zero results.
When all is said and done, a design system is a tool that needs to fit your needs, and while I’ve given an approach here that I hope is useful and helps get you off that starting line, it’s important to remember that whatever you do needs to work for you which leads me to one final option that you might wish to consider.
Use an existing system.
Adopting a system like Tailwind, Material UI, or one of the many others might work out to your benefit if you’re a small team or even a big team. Not only are you getting prebuilt frameworks for both design and development teams, but your documentation is also complete and maintained.
You can always slowly modify these systems to meet your needs and build upon them as you grow rather than starting from scratch. It might seem like a big task at first, given the potential cost (in terms of work) that might come along with it, but don’t forget that investing in a custom system can also be costly if you’re a small team.
Thank you for reading my article. I use writing as a way of thinking aloud and organising my thoughts, so I hope you found it useful. Please feel free to share it, and if you have any questions, please let me know.
Design systems: simplifying documentation writing was originally published in UX Collective on Medium, where people are continuing the conversation by highlighting and responding to this story.
