How much documentation to include in a style guide?

I was asked this question on Twitter:

It’s a question I often hear from the design systems teams I work with. The short answer is: include as much or as little documentation as needed. The longer answer is: it depends. Alright, now I’ll quit messing around and explain a bit more.

The style guide is the storefront environment where all of the design system’s ingredients are put out on the shelf for everyone to see. A component showcased in a style guide can be bolstered by a whole lot of other information (such as description, usage, context, code documentation, examples, people, meta info, etc). But what content, functionality, and documentation to include depends very much on who is visiting the style guide website and what they need to accomplish with the system.

Who are the makers and users of the design system? Users of a design system often have different goals and motivations from the design system makers. The minutiae of the design decisions that go into a component might be interesting or helpful for the makers of the system, but users may very well not care that much about how the sausage is made. If the users of the system are different product teams, external agencies, or other

For the Unity design system, our research and interviews with developers painted a picture of harried engineers who needed to quickly execute UIs. The style guide’s design needed to recognize that reality, so it became important to respect engineers’ time by not bludgeoning them with mountains of design documentation. So we included terse usage definitions for component variations to help users determine which variation to reach for:

For other components, however, we needed to paint a fuller picture of when to use a component (or even when to consider an alternative component). For instance, the Button Bar component:

needed a bit more explanation about how to properly use it.

While more verbose than the terse usage guidelines of the button variations, the bulleted list of guidelines help developers understand what the component is good for and why they would reach for it.

Of course every system is different, and the audiences for each style guide website can have wildly different goals and expectations. I’d imagine the massive scale and reach of the Material Design system influences how comprehensive their documentation is. Look at the documentation for the floating action button component: it’s massive! They didn’t expend all that energy to create all that documentation arbitrarily. The goals, expectations, and needs of the design system’s users need to determine the shape and amount of documentation in the style guide.