A Guide to Implementing Support Documentation For Your Design System

Let’s talk about a framework for building support documentation as a key part of your design system creation.

Design system documentation is not an afterthought but a part of the design and development process. But for less disciplined teams, who work on documentation post-release or during release, the system lacks quality of information. Why? For example, after the code is merged, naming props are consistently overlooked. A button can be mistaken for a link. If a design team feels a component should not be allowed to do a certain thing, it should be documented so those edge cases are not built during development.

Your adopters will also appreciate the documentation you have created for each component. A thorough documentation should consist of visual language guidelines, code guidelines, accessibility guidelines, getting started, release notes and support process at the very least.

If your team lacks support resources, good documentation can fill the void of a support team. When you have a flood of questions coming in, you can direct them to the central documentation site or hub.

So how do you make documentation a part of your team’s workflow?

Regardless of how your system team is structured, your team is responsible to build the entire feature of a component—visual design, UI, UX and release notes. This is what your system team needs to deliver. How you build and deliver is up to you. A good workflow, however, should account for documentation. Let’s see how!

Discovery → Design → Build → Doc → Publish

I learned this workflow process from Nathan Curtis who is a design system expert and was once upon a time my mentor. I can’t imagine working without this framework. Even ticket names in JIRA are labeled as one of these to identify at which step of the process the team is at with a given component.

A word of caution on the workflow. These steps can overlap or can be revisited at any time of the process. They are not sequential, meaning one doesn’t have to be done before moving on to the next. Build and Doc can both be worked on in parallel. But Design needs to be completed before the Build happens.

1. Discovery

This is the first step of a new feature. This requires competitive analysis, analysis for internal need and collaboration with potential adopters. What to pursue and not to pursue is the goal of this journey.

Discovery can be broken down into divergence and convergence.

Initial discovery should be as divergent as possible, meaning look at every potential use case, limitations and relevance. (Check out my previous article for more ideas for a complete discovery phase.)

Then present your discovery findings to the team. After receiving feedback and making some decisions, it is time to narrow down the discovery and document your findings. This is called convergence. Ideas on what to do start to emerge.

This can be done by anyone—a developer, designer or product manager. But it should be done by someone who has more context on the need of this feature.

2. Design

The design step explores permutations and combinations of a component. How many variations should a component have? What about sizes and pairing other elements as a sub-component? Design should also explore visual style and visual patterns.

Once the design decisions have been concluded, a designer should collaborate with other designers during a critique session. This ensures consistency and standardization. Designers are usually critical, so getting input from other designers only solidifies all edge cases.

After decisions have been made on final design, a designer should finalize wireframes and documentation. Documentation should be as extensive as possible for hand-off to a developer.

This step is usually carried out by a designer.

3. Build

The build step results in turning design into code. Generally, the code is built using HTML, CSS and JavaScript. There are also many JavaScript frameworks. The goal here is to ensure code is aligned with design needs. For example, code should support different variations and sizes.

Once the code is written, there should be unit test and visual test coverage to prevent any unforeseen failures. Once the code is finalized and approved, a developer should work with the designer to ensure quality and standards of a component are met.

After the code is merged, the documentation should be supplemented by a developer. This documentation showcases installation, usage, all available props, events and slots if applicable. Great documentation should also support accessibility with appropriate aria-labels.

The build step is generally conducted by a developer, but a designer with a development background should not shy away from carrying out this step.

4. Doc

After the code is merged, documentation from design and development should be merged in a central place.

Doc should cover design standards, code standards, variations and sizes available on a new component, supporting examples (interactive if possible), accessibility documentation, supporting images, change-log and other useful guides.

This documentation can be authored by a developer, designer or a product owner. Once the documentation is authored, it should be edited by at least two team members to ensure no detail is skipped. Thorough documentation leads to fewer questions, which ultimately allows a system to grow.

5. Publish

The final step is pretty straightforward. All documentation should be published at a central location. It is important to support one documentation hub as opposed to managing many hubs separately for designers, developers and product managers.

There are many design systems that are hosted publicly. This is done for different reasons but mostly to support adopters and attract outside talent. Design systems are an integral part of branding today. In the digital world, your design system can showcase your organizational strategy digitally without saying much.

Whether your design system is hosted publicly or privately, ensure the whole team has access to it.

The final step of publishing can be carried out by anyone on the team.

Conclusion

All five steps—Discovery, Design, Build, Doc and Publish—are not necessarily meant to be followed sequentially, but together they tell a neat story of progress being made for each component being built. If a team is building three components simultaneously, a product manager can track down which step of the process a component is at. This also allows a design system to communicate to its users and set expectations on the delivery schedule accordingly.

As you can also see, documentation plays a role from the beginning to end. While the documentation is not needed in each step, it does play an important role of communication and collaboration.

Imagine if a developer does not know what not to build, but a developer builds anyway. Imagine if a designer does not provide documentation on spacing. How hard would it be for a developer to know what padding and margins to apply? That is one quick way to lose consistency for your final product.

And one more thing—you should document what your framework is for how you build components. These steps are just one framework for creating documentation, but whatever strategy your team follows, you should communicate that with your users on your documentation site or hub.