Great documentation is key to the success of any design system—but getting it right and keeping it up to date can be a challenge. How do you know where to begin? What should you include? At Knapsack, we advocate for “Strong opinions, loosely held.” We have strong views on best practices but understand that these may evolve based on your specific design system and organizational needs.
With countless ways to structure documentation and an endless list of potential content, getting your team’s documentation up and running can feel overwhelming. That's why we’re sharing some of our "strong opinions" to help you get started. This guide includes general best practices for any design system, along with Knapsack-specific tips that can help you maximize our platform’s features.
Assemble the Right Team for Success
Building and launching a great documentation site requires some research, user testing, iteration, QA, and maintenance. It’s a significant responsibility, so we recommend assembling a team with the following key roles:
- Champion: A senior leader who advises, secures resources, and advocates for the project.
- Product Owner: The person responsible for the product, managing timelines, delegating work, and guiding the vision.
- Implementation Support: A mix of designers and developers who create content and set up the documentation site.
- Other Stakeholders: Individuals with a vested interest in the final product who offer feedback and make decisions.
Keep in mind that, depending on your team size, individuals may take on multiple roles. However, the Product Owner and Stakeholders are the most critical to identify. Clarity on who owns the project and input from users are essential to creating a documentation site that serves your team and organization effectively.
Create a Content Strategy for Your Design System Documentation
If you can get help from a content strategist to create your documentation site, do it! But even if you can’t, anyone working on design system documentation should approach the task as a content strategist would. Here are some tips to guide you:
Understand the assignment
It is important to gather some key information that will inform your decision-making throughout the process. Revisit these questions as needed:
- What is the purpose of this content? Why is your organization building a design system, and what do you want to achieve with this documentation?
- What workflows will need support? What will people do with the content (e.g., editing, sharing, versioning)? What permissions and controls will be required?
- What tools and functionality are needed? What does the documentation site need to integrate with, and how should it function to support the stated goals?
- Who is responsible for what? Work with stakeholders to identify the users, governance structure, and maintenance plan.
Tailor your content
Different roles require different information. Designers, developers, and product managers all have unique needs, so ensure your documentation is structured in a way that makes it easy for each audience to find what they need. For example:
- Brand and usage guidelines for designers.
- Code documentation for developers.
- Status sets for PMs
Remember to speak in the language of your intended audience. If you are writing a technical document for the developers, get a developer or two to review your content to make sure it’s in language that is familiar and clear to the end user.
Finally, consider how different people consume information and learn. Where you can, Include multimedia content to support the different styles of learning that are present across all teams and organizations.
Iterate on Your Information Architecture
How you structure information matters. Spend time thinking about and iterating on your design system documentation information architecture (IA). Even before you start writing, create a proof of concept. Sketch it out, gather feedback, and make adjustments A round or two should be sufficient, and remember that you can’t make everyone happy or plan for every possibility.
We've provided an example of how you could structure your documentation, but again, it's all dependent on what you need.
Pro Tip: Knapsack pages automatically generate a table of contents (TOC) that links to each section of the page. Use the page settings to define what heading indicates a new section and, Poof! You have a TOC block for easy navigation.
.png)
Essential Components for Design System Documentation
Regardless of how you structure your documentation, there are some essentials we feel need to be included to create the best possible documentation and get the most use out of your design system.
Spoiler alert! Some of this is only possible with Knapsack. If your current platform or homegrown solutions don’t let you include these elements in your documentation, consider taking a closer look at Knapsack.
- Brand & Usage Guidelines: This section is primarily for designers but can be useful for other teams as well.
- Do’s and don’ts
- Visual/contextual examples
- Design references - Import design assets from Figma and see them contextualized alongside documentation.
- Live Code Rendering / Prototyping Playground - Visualize the coded component as it will appear in the final product alongside documentation and design.
- Use Knapsack’s prototyping functionality to experiment with coded variations with all the information you need in one spot.
- Status Sets: Use Knapsack’s native content block to track the status of components and ensure everything is up to date and ready to go.
- Accessibility - Because of the importance and specialized nature of this content we strongly advocate for dedicated accessibility documentation, no matter what platform you use.
Pro Tip: Knapsack includes a library of native content blocks, but you can also embed your custom components using template blocks to create exactly what your team needs. Check out our help docs for more information.
Make a Plan to Maintain Your Design System Documentation
Documentation is a living thing—it requires regular updates to stay relevant. Maintenance can be a challenge and it’s easy to overlook. That’s why we’ve stressed the importance of establishing ownership of this task from the beginning. We strongly recommend creating a plan and clear guidance on when, how, and by whom the documentation will be updated.
Knapsack helps ease the maintenance burden by dynamically linking design, code, and documentation assets. This means that when changes are made to source files, documentation updates automatically. For example, add a new button in React, and it will appear in Knapsack’s documentation. Review our help docs to understand how this connection works and what controls are available to manage this process.
Hopefully, this guidance helps get you on the right path to creating awesome documentation. Remember, it’s going to take time and effort to get this right and you’ll need to iterate. Be mindful of your audience, gather feedback, and adjust along the way. And as always, Knapsack is here to help.
