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.
\nThat’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.
\nEvery Northwind component page follows the same order, so people learn where to look:
\nDialog.Title”).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.
\n\nTwo 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';\nimport { Button } from './Button';\n\nconst meta = {\n component: Button,\n tags: ['autodocs'],\n args: { children: 'Assign driver' },\n} satisfies Meta<typeof Button>;\nexport default meta;\n\ntype Story = StoryObj<typeof meta>;\n\nexport const Secondary: Story = {};\nexport const Primary: Story = { args: { variant: 'primary' } };\nexport const Danger: Story = { args: { variant: 'danger', children: 'Delete route' } };\nexport 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.
\n\nDocumentation 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.
\nThen 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.
\n\nIn 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.
\n","toc":[{"id":"sec-1","text":"Anatomy of a component page","level":2},{"id":"sec-2","text":"Generate what drifts, write what can’t be generated","level":2},{"id":"sec-3","text":"Docs are part of done","level":2}],"takeaways":["People scan documentation for a copyable example and a yes-or-no answer to “should I use this?”, so put those first.","Every component page needs “when to use” and “when not to use”, with links to the right alternative.","Generate props tables and examples from code and stories so they can’t drift; write by hand only what code can’t express.","Documentation is part of the definition of done and ships in the same pull request as the component change."],"further":[{"title":"Writing docs with Autodocs (Storybook, official repository docs)","url":"https://github.com/storybookjs/storybook/blob/next/docs/writing-docs/autodocs.mdx"},{"title":"How Users Read on the Web (Nielsen Norman Group)","url":"https://www.nngroup.com/articles/how-users-read-on-the-web/"},{"title":"Button component page (U.S. Web Design System)","url":"https://designsystem.digital.gov/components/button/"}],"quiz":[{"q":"Analytics show most visitors to Northwind’s Button page leave within 40 seconds after copying the first code example. What should you conclude?
","options":[{"text":"The page is failing, and people should be made to read the whole page.","why":"Quick visits are often success: they found the example they needed. Forcing reading fights how people work."},{"text":"The first example should be the most common correct usage, with the most important guidance right next to it.","why":"Correct. If the first example is what gets copied, it decides what ships, so it must model the right default."},{"text":"The code examples should be removed so people read the guidelines.","why":"Removing what people need most sends them to copy from other products’ code instead, mistakes included."},{"text":"The page needs more variants in the first example.","why":"A busy first example is harder to copy correctly; show the common case first and the rest below."}],"answer":1},{"q":"Teams keep using the Danger button for “Remove filter”, which isn’t destructive. Which documentation change helps most?
","options":[{"text":"A longer description of the Danger button’s colors.","why":"Color details don’t tell anyone when the variant is appropriate."},{"text":"A props table entry forvariant="danger".","why":"The props table shows the option exists; it says nothing about when to choose it."},{"text":"A “when not to use” note with a do-and-don’t example, pointing to the secondary variant for reversible actions.","why":"Correct. It names the exact misuse and gives the alternative at the moment of decision."}],"answer":2},{"q":"The Button props table in the docs lists a kind prop that was renamed to variant two releases ago. What’s the durable fix?
Dispatchers complain that the app keeps interrupting them: six teams now open a blocking Dialog that says “Route saved!” after every save. You check the Dialog docs page. It opens with a live demo of exactly that success dialog, followed by a complete props table. There is no guidance on when to use Dialog versus Toast. Which changes would you make? Select all that apply.
\n","hints":["Remember which part of a page gets copied the most.","Good fixes act at the moment someone decides which component to use, inside the docs page itself."],"explanation":"The first example is the most-copied code on the page, so it was teaching the misuse; replacing it with a real blocking decision, like “Delete route?”, changes what gets copied. A “when not to use” line and a do-and-don’t pair name the exact mistake and point to Toast at the moment of decision. More props detail, a principles link, or answering teams one by one in Slack leave the page itself unchanged, so the next team repeats the mistake.
\n","checkLabels":{},"optionText":{"when-not":{"text":"Add “When not to use: confirmations that don’t need a decision. Use Toast instead.” near the top of the page.","why":"Correct. It names the misuse and the alternative where people decide."},"props-detail":{"text":"Expand the props table with more detail on theopen and onOpenChange props.","why":"The props work fine; the teams chose the wrong component, which the props table can’t address."},"first-example":{"text":"Replace the first example with a blocking decision such as “Delete route?” with Cancel and Delete actions.","why":"Correct. The first example is what gets copied, so it must model the right use."},"principles":{"text":"Add a link to the design principles page at the top of the Dialog page.","why":"Principles are general; nobody follows a link to find out whether a save message should block the screen."},"do-dont":{"text":"Add a do-and-don’t pair: Dialog for “Delete route?”, Toast for “Route saved”.","why":"Correct. Side-by-side examples make the boundary between the two components obvious at a glance."},"slack":{"text":"Reply to each of the six teams in Slack explaining the problem.","why":"It helps those six teams once, but the page still teaches the next team the same mistake."}}},"words":740,"readMinutes":4}