Documentation People Actually Read

Northwind’s first documentation site had 140 pages, a beautiful typeface and a principles section that took a month to write. Our analytics told a humbling story: on component pages, the median visit lasted 38 seconds. People landed, scrolled to the first code block, copied it, and left. The principles section averaged nine visits a week, most of them from our own team.

That’s not a failure of the readers. Engineers and designers open documentation in the middle of a task with one question: “Is this the right component, and how do I use it?” Good documentation answers that in the first screen and keeps everything else one scroll away.

Anatomy of a component page

Every Northwind component page follows the same order, so people learn where to look:

1. One-line description of what the component is for.
2. When to use, when not to use, with links to the alternative. “Use Dialog for decisions that block the current task. For non-blocking messages, use Toast.”
3. The primary example: a live demo of the most common correct usage, with copyable code.
4. Examples of each variant and important state, each with its own code.
5. Accessibility: keyboard behavior, what screen readers announce, and a split between what the component handles and what the team must still do (for example, “you must give every Dialog a Dialog.Title”).
6. Content guidelines: how to write labels and messages. “Button labels start with a verb: Assign driver, not Driver assignment.”
7. Props table, generated from code.
8. Status and history: stable, beta or deprecated; the version it was added; links to the changelog.

The order follows what people need under time pressure. The decision (“should I use this?”) and the copyable example come first; reference material comes last.

Generate what drifts, write what can’t be generated

Two parts of a docs page go stale fastest: props tables and code examples. Both can come from code. Props tables are generated from TypeScript types. Examples come from stories, the same files used for development and visual tests. In Storybook, a story file with the autodocs tag gets a generated docs page with a live preview, the story’s code, and a controls table built from the component’s props:

import type { Meta, StoryObj } from '@storybook/react-vite';
import { Button } from './Button';

const meta = {
  component: Button,
  tags: ['autodocs'],
  args: { children: 'Assign driver' },
} satisfies Meta<typeof Button>;
export default meta;

type Story = StoryObj<typeof meta>;

export const Secondary: Story = {};
export const Primary: Story = { args: { variant: 'primary' } };
export const Danger: Story = { args: { variant: 'danger', children: 'Delete route' } };
export const Small: Story = { args: { size: 'sm' } };

What code can’t generate is judgment: when to use the component, when not to, how to word its content, and why the system made the choices it did. That’s where the docs team’s writing time goes.

Docs are part of done

Documentation that ships later doesn’t ship. Northwind’s pull request template for system components has a checklist: stories for every variant and state, an updated docs page, an accessibility section, and a changelog entry. A component change without them doesn’t merge. Because the docs live in the same repository as the components, they’re reviewed in the same pull request by the same people.

Then treat the docs like a product. Northwind tracks three signals: search queries that return no results, the questions asked in the design system Slack channel, and pages with high exit rates right after the “when to use” section. Each repeated question becomes a docs change. If the same question arrives three times, the answer belongs on the page, not in a thread.

In the exercise, you plan the documentation fixes for a real misuse. That completes the components section; next, you connect the design side and the code side of the system so they stay in sync.