Chapter 5

Documentation

Chapter 5

Documentation

It's time to create a "map with pin-points" and instructions on where to find things. Documentation is where we collect assets, source files, code, design principles, animation styles, and guidelines for using the components.

Documentation is useful only when people know how to use it, and we often need to remember that. We are talking a lot about people working on the design system but not design system consumers. They need to know where to find the detailed structure of the assets, variants, hacks for optimized work, or recommended plugins. Have that in mind when choosing a platform and writing the instructions.

Usually, teams that have low design system coverage find all sorts of excuses. For example:

We were not sure if we could detach the component,

so we quickly created something new.

We were not sure if we could

detach the component,

so we quickly created something new.

We need guidelines for complex use-cases.

We need guidelines

for complex use-cases.

We came up with a different scenario that
was not included in the specifications.

We came up with a different scenario

that was not included in

the specifications.

The rules are so strict we can't be creative anymore.

The rules are so strict

we can't be creative anymore.

As you can see, all of them lead the documentation. So its primary goal is to provide guidelines for all consumers (employees).

Everyone needs access, and everyone needs to understand how to use the documentation.

Don’t write poetry.

Don't use jargon and fancy words.

Write how you've done it in simple language, explain where to use it, and add guidance for using it again.

Be as straightforward as possible. Don't write essays; no one will read them.

People using the design system will only use the components when they fully understand the specifics.

Clear and thorough documentation is an essential part of any design system.

EVERYTHING SYNCED

A Single Source of Truth?

A single source of truth in design systems is like having one special rulebook where we save all the rules and all the information is regularly updated

For example, if I change the primary red color in Github, the change is automagically pushed and updated everywhere we use it.

Your design system

Development

iOS

Web

Marketing

Design

User

Your design system

Development

iOS

Web

Marketing

Design

User

How to choose the right tool for the documentation?

Start by answering these questions:

How will other teams contribute?

How detailed will your instructions be?

In what form will you add your code snippets?

Do you want to include the code

or embed stories from Storybook?

Will you provide live previews?

Do you want to include the code

or embed stories from Storybook?

Do you want to include downloadable assets?

Do you want to include

downloadable assets?

Who are our consumers?

How many design system maintainers do we have?

How to choose the right tool for the documentation?

Also, consider the following:

Ease of use

How easy is it to embed designs, code, downloadable assets, connect pages, etc.

Integration with other tools

How easy is it to connect with other tools? Is it plug-and-play, or is there much going back and forth for things to work?

Collaboration

How easy is it to add new team members? How expensive is it to add the whole team? Can you add specific rules? Can you lock certain content (for public use, for example)?

Built-in resources (templates, guides)

Does the tool provide any guidance for setting up the whole ecosystem? Do they offer some templates for writing or structure for adding content?

Make it logical

Organize, baby, organize.

One search per day makes

the stress go away.

Before you start uploading your stuff and code, think about the structure and the language. Make it predictable and discoverable. Make sure everyone understand what you are writing about.

Do it iteratively.

Step by step.

One search per day makes

the stress go away.

Try out different approaches, put it in the wild, collect feedback and adapt quickly. Feedback loop is important, since organization's needs will change and grow over time.

Make it relevant

An outdated design system is like no design system.

One search per day makes

the stress go away.

Write instructions in human language.

Make it searchable

Powerful search per day makes
the stress go away.

One search per day makes

the stress go away.

Save the user's time and make it easy to skim through the docs.

What to include?

Each section should be easy to understand. Don't overcomplicate.

Components

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:

Brief explanation
Explain where it lives in the user flow
Add live examples
Include code snippets
Include Figma links (embeds)
Include examples
Include DO's and DON'Ts
Add combinations with other components
Add specific rules
Add the status of the component
Add responsible person

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:

Brief explanation
Explain where it lives in the user flow
Add live examples
Include code snippets
Include Figma links (embeds)
Include examples
Include DO's and DON'Ts
Add combinations with other components
Add specific rules
Add the status of the component
Add responsible person

Add details of where, when, and why to choose it. Explain how the component can be combined with others to make the user flow as smooth as possible. Add details, such as:

Brief explanation
Explain where it lives in the user flow
Add live examples
Include code snippets
Include Figma links (embeds)
Include examples
Include DO's and DON'Ts
Add combinations with other components
Add specific rules
Add the status of the component
Add responsible person

Documentation structure

Getting started

Introduction

About

Contributions

What’s new?

Changelog

Monthly updates

Roadmap

Dependencies

Component status

Brand

Logo versions

Who we are

Typography

Strategy

Design Principles

Illustrations

Presentations

Motion

Colors

Tone of Voice

Design Tokens

Background colors

Border Color

Border Radius

Box Shadow

Duration/Transition

Elevation

Font Size

Font Weight

Font Family

Grid

Line Height

Responsiveness

Shadows

Size

Space

Transition

Z-index

Components

Avatar

Activation cards

Badge

Box

Buttons

Callout

Card

Checkbox

Code snippet

Column

Date picker

Dropdown

What’s new?

File uploader

Form

Link

List

Notification

Pagination

Popover

Tab

Tooltip

etc.

Design Documentation Template

Simplify your handoff with this useful documentation template. You can easily customize all the styles and adapt them to your needs. Yay. 🌈