How to write good documentation
Jules Mahe
A common saying goes, “if it is not written down, it does not exist”; and this is especially true for design systems. You’re just using a component library as long as you don’t have documentation explaining how to use your components and patterns. A design system’s documentation is at the heart of the system, but its ungrateful nature makes it the least appreciated. Not everyone enjoys writing or reading documentation.
What is the best way to create good documentation while ensuring your teams read it? Design often answers questions through workshops, and this time will not be an exception. The following workshop is designed to ensure that your documentation is used properly and to ensure that your patterns are documented efficiently. You can also duplicate this Figjam template to help you start this workshop on the right track.
Set-up
In order to conduct this workshop efficiently, you’ll need to learn a few things before you begin.
Who to invite?
You should invite all the “makers” of your projects who understand how to use your system’s components and patterns. You’ll most likely need designers and developers, but you could also need product managers if that makes sense; invite whoever you think is relevant.
To ensure the workshop remains efficient, try having fewer than 10 participants. Your workshop risks being longer if you invite more people, as everyone will want to speak. On the other hand, the more people you invite, the more likely they are to adopt your documentation. As participants in this workshop would have contributed to this design system and would feel involved, they could serve as potential advocates for your documentation (as well as your design system). In addition, they may want to share their contribution with more people. Basically, this workshop is a good way to spread your design system within your company.
How long?
2 hours would be ideal so that you could have a thorough introduction, give people time to think and write the famous guidelines.
For the person facilitating the workshop, it is also strongly recommended to have at least 1 hour afterward to consolidate the results. Set up this workshop with this extra hour in mind.
What do you need?
It’s advisable to start with a pattern you already know. Having a prioritization component workshop would be more beneficial, so you can have a backlog and know which components should be documented first.
Once you’ve decided what to document, gather screenshots of the pattern or component you use across your projects: your blog, your product, your newsletter, your website, your app, etc. The more you know about how it is used, the better. With these screenshots, your attendees can better understand what’s working or not so that writing guidelines and making decisions will be easier.
Step 1 – Identify the actual use (10-20 min)
You can display all the screenshots of your different projects and ask your attendees to add a sticky note describing how each pattern or component is used. For instance, a color pattern could be used for actions, icons, illustrations, links, titles, backgrounds, etc. Each participant should do this for each project and screenshot to define how your pattern is actually used.
Step 2 – Define the right use (20 min)
After you figure out how your pattern or component is used in your actual projects, you will need to decide whether to make adjustments. From the previous step, organize the sticky notes by category by describing the actual use. It may be the same thing (as in actions), or it may be part of the same idea (as in icons and illustrations about brand identity).
Once you have your categories, have everyone vote on their favorite usage with a thumbs up and against with a thumbs down. You will probably engage in some debates and interesting discussions at this point. Your team is in the process of aligning itself.
Try to guide them in their discussions, but avoid creating frustration or endless speeches. Having an overview of what people think about this pattern or component will help you write your first guidelines.
Step 3.1 – Write your first guidelines (20 min)
Once the voting phase has been completed, display all the categories that got a thumbs up in the table rules section. Organize the categories one per line to the left of the table.
There are three questions we must answer for each line: why, how, and when?
- Answer the “why” by considering whether it is used to indicate something, respond to something, or respond to a particular event. Find out why you are using it.
- When it comes to “how”, ask yourself whether it should be used in a specific way, with another element, etc. Find out how you should use it.
- Regarding “when”, consider if it should be used for a particular need, for a specific action, after an event, etc. Find out the right moment when you should use it.
Step 3.2 – Illustrate with examples (15 min)
The best documentation is one that people will want to read, so visuals are always helpful. As a result, after you write your first guidelines, please look for existing examples to show the rules you just defined. If there is no actual example yet, try annotating a screenshot or drawing a sketch to make the idea more visual. Taking the time to do this ahead of time will save you time later on. By doing so, you will be able to build solid and efficient documentation examples. Your examples will be easier for you to find if you already have detailed information.
Step 3.3 – Define your dos and don’ts (15 min)
The person who reads your documentation will always appreciate it when you define this part. Making sure people know how to use or not use a particular component or pattern is a good way to ensure mistakes don’t happen.
- Dos can be a reminder of some very important rules you defined. Additionally, it’s a handy way to highlight some of the most significant features or best practices.
- Don’ts are usually easier to define. Due to phase 2 with all the categories that got a negative vote (thumbs down), you probably already have some don’ts. You can use this to illustrate your don’ts. After that, you can use one of the dos to explain what you shouldn’t do if relevant.
Whenever possible, try to use visuals and examples to illustrate what you should do and what not to do, so your documentation is easy to read and understand.
The next steps
The end is near! As a result of conducting this workshop, you now have your first guidelines. In addition, your attendees’ engagement will help your design system gain adoption and engagement. However, it’s not quite over; here are a few other steps you should take after the workshop.
Make it real
You should write up your guidelines properly while you still have all the ideas and examples fresh in your mind as you’re still fresh following this workshop. It is important to consolidate the guidelines as quickly as possible, whether using zeroheight or another documentation platform. Otherwise, you risk leaving it as a draft and never getting your documentation published.
Share it
Now that you’ve written the proper guidelines in your documentation tool, it’s real. Sharing the newly created documentation page can involve your attendees and a wider audience. Maybe there’s a good opportunity to communicate about how your design system is progressing if you have a channel in Slack, Teams, or another internal messaging tool.
Use your attendees as advocates
You’ve generated a lot of engagement among your attendees. Use this dynamic to grow your design system by asking them to share the documentation you’ve just created with their teams. This is an effective way of spreading your design system, gathering feedback, and getting more people acquainted with it.
Press repeat
This workshop can only benefit one component or pattern. You might want to consider having this workshop as part of a regular meeting if you want to document everything correctly. For example, could it be a two-hour weekly event?
If you coordinate this workshop with your design system backlog, it could even provide you with a roadmap to know when your system’s next patterns and components will be documented. By making this a habit, you can ensure high quality for your documentation and your design system adoption and engagement.
Taking advantage of this workshop will help you begin documenting your components and patterns. It is important to note that this is only the beginning and that this documentation could be expanded through accessibility, technical aspects, editorial rules, tone & voice, etc. It’s up to you to add extra information and details to your documentation for your design system. To make this workshop run smoothly, here’s a Figjam template you can reuse with your team to help get things started. Don’t hesitate to share it and give us your feedback!