EightShapes
Published in

EightShapes

Documenting Components

Serve a System’s Audiences with Well-Architected Content

Audience

First things first: who it is this for? And since the answer usually spans more than one discipline, who’s more important?

Engineers, Designers, and Everyone Else!

When a library offers code, engineers are an audience. Obviously. If a library is only code, should doc serve designers too? If doc only offers design guidance without code (e.g., Google Material), do engineers care?

Engineers, then Designers, then Everyone Else

Serving everyone doesn’t mean serving each equally. Engineers may visit doc 5, 10, or even more times daily. It may even be an open window adjacent to their code editor! A designer may visit less frequently, comparing this to that and occasionally absorbing details. A content strategist or researcher may visit rarely to support a decision.

Content

Component doc connects the your audience with content you can provide. The content takes many forms, they don’t all cost the same, and it’s up to you to weave them together.

  1. Examples illustrating a component’s named variation, states, and other dimensions, preferably paired with and rendered by code instead of presented via static images. (Required)
  2. Design Reference including Use Whens, Do’s and Don’ts, and guidelines for visual, interaction, and editorial concerns. (Recommended)
  3. Code Reference detailing the code’s API (such as Props) and other implementation concerns. (Required, if code exists)

Content Production Cost Varies by Type

The cost of each varies. An Introduction should be quick and cheap, riffing off an example to write a sentence or two. Well-organized Examples are an essential investment, over time becoming predictably produced. Code references should emerge via straightforward if tedious templates that engineers use to fill in the blanks.

Architecting the Component Page

Design & Code: To Fragment or Combine?

In practice, component doc can emerge from both deliberate choices and unfavorable constraints (“get it out there!”). Often, component doc ends up a split story: designers publish for designers here, engineers publish for engineers there. This fragmentation can occur by accident, design, or both. As a result, discuss a component page’s information architecture early.

Google Material propagates stories across Material Design, Material Design Lite, and Material UI’s Demos and API.
Component design guidance and code & API docs, loosely coupled via separate sites. Example: Atlassian.
  • Features diverge: design expresses deep features unachievable in code, or code articulates undesigned outcomes.

For Threaded Content, Stack or Tab?

In many systems programs I’ve led in recent years, such as the Morningstar Design System, we’ve thread design and code together. Adopters find unified names, guidance, and narratives on how to use variations and features.

Component documentation page that threads design and code content together in one scrollable view, as shown in Morningstar Design System.

Grouping and Ordering Content by Type

Whether stacked or tabbed, I’ve come to advocate for a consistent content order and priority of:

  1. Examples—the venerable “goods” they are most after—front and center.
  2. Design guidance expanding on examples yet drifting into storytelling of uncertain length.
  3. Code reference, predictably structured and dependably authored. If engineers are the priority and Props paramount, elevate that reference table into a dominant position.
Distinct approaches varying what content is prioritized: Code (in Examples) first, Design first, or a sensitizing example above tabs altogether

For Longer Pages, Anchor Readers with Persistent Local Navigation

The longer your page, the more important it is to signal what’s there and where you are. Vertical local navigation in a right rail works effectively: ever present, tracking page location as you scroll, and expanding to reveal sub-headers along the way.

Morningstar Design System organizes local navigation along a page’s right rail with two levels of hierarchy.

Showing Design OR Code Or Both?

The more design and code thread together, the more audiences interested predominantly in one over the other will ask to refine the page’s interface to suit what they want to see.

  • “Design Only” could hide code snippets and overtly technical guidance like tables of Props or CSS Modifier Classes.
  • “Code Only” could hide lengthy sections on visual style and editorial considerations, but still reveal some guidance — Use Whens, in particular –relevant for engineers.
Hudl’s Uniform design system distinguishes guidance for Design and Code via a page-level toggle (upper right).

--

--

A collection of stories, studies, and deep thinking from EightShapes

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Nathan Curtis

Founded UX firm @eightshapes, contributing to the design systems field through consulting and workshops. VT & @uchicago grad.