Documenting components in a Design System

Good documentation requires planning, effort and process to make examples and guidelines that make a difference. You need to build for an audience, figuring out what content and architecture they need. The following is an overview for structuring your documentation.

Audience

Focus on engineers and designers, but consider accessibility, product mangers, QA, etc. Try to optimise for both engineers/designers, but consider slightly preferring engineers if they will probably refer to it more. Code = final product, at the end of the day.

Content

Four broad areas:

• Introduction
• Examples (variations, states, etc.) preferably powered by code
• Design reference (use cases, dos and donts, guidelines)
• Code reference (API, props, etc)

The priority will usually match the above order

Architecture

Design & engineering overlap in the desired documentation, but each also have their own desires. Be wary of splitting design/code information, as it's easy for them to get out of sync. A single source of truth is ideal, but don't bore disciplines with info they don't care about.

Threaded content

Blending the two disciplines together is definitely possible, and it can be solved in different ways:

• Stacked content, on one page
• Tabs
• Toggle between design/code

For longer pages, add navigation helpers (e.g. scrolling table of contents)

[[20211108133114-documenting-components-design-system-content]]

https://medium.com/eightshapes-llc/documenting-components-9fe59b80c015

[[components]] [[design]] [[designsystem]] [[documentation]]