K
Klivvr Blog

Documentation That Developers Actually Read

How to create design system documentation that developers engage with, covering information architecture, interactive examples, API references, and documentation-as-code workflows.

business12 min readBy Klivvr Engineering
Share:

The graveyard of design systems is full of beautifully built component libraries with documentation nobody reads. You can have the most type-safe, accessible, thoroughly tested components in the industry, and it will not matter if developers cannot figure out how to use them. Documentation is not a chore to finish after the "real work" is done — it is a core product feature that directly determines adoption, correct usage, and developer satisfaction. This article covers how to build documentation that developers actually engage with, from information architecture to interactive examples to sustainable maintenance workflows.

Why Most Documentation Fails

Most design system documentation fails for one of three reasons, and understanding these failures is the first step toward doing better.

It is organized for the writers, not the readers. Documentation structured around the system's internal architecture (primitives, composites, patterns, utilities) makes sense to the team that built it. But a product developer looking for "how do I build a form" does not think in those categories. They think in tasks.

It lacks runnable examples. A prop table tells developers what is possible. A code example tells them what is practical. Without examples that they can copy, paste, and modify, developers are left guessing at correct usage patterns. Static screenshots are even worse — they become outdated the moment the component changes.

It rots. Documentation written once and never updated is worse than no documentation at all, because it teaches developers to distrust everything they read. If the prop table says variant accepts "primary" but the actual TypeScript type also includes "ghost", the developer learns that the docs are unreliable.

The solution to all three problems is the same: treat documentation as code. Automate what can be automated, test what can be tested, and build workflows that make documentation updates a natural part of the development process.

Information Architecture: Task-First Organization

Organize your documentation around the tasks developers need to accomplish, not the component taxonomy. The entry points should be:

Getting Started — installation, basic setup, first component rendered. This page should take less than five minutes to complete. Every unnecessary step is a potential drop-off point.

// The Getting Started page should show exactly this much code
// and produce a visible result
 
// 1. Install
// npm install @messier/core
 
// 2. Import styles (once, at your app root)
import '@messier/core/styles';
 
// 3. Use a component
import { Button } from '@messier/core';
 
function App() {
  return <Button variant="primary">Get Started</Button>;
}

Component Reference — one page per component, each following an identical structure: overview, live examples, prop API, guidelines, and related components. Consistency in structure means developers know exactly where to look on any component page.

Patterns — task-oriented guides that compose multiple components: "Building a form," "Creating a data table," "Implementing a settings page." These are the most valuable pages in your documentation because they answer the question developers actually have.

Theming — how to customize the system, create brand themes, implement dark mode. This is its own section because theming cuts across all components.

Migration — guides for moving from other systems or previous versions. Include codemods, before/after examples, and breaking change lists.

Every page should be reachable in two clicks from the homepage. If a developer has to navigate through three levels of hierarchy to find the Button documentation, you have already lost them.

Interactive Examples That Teach

Static code blocks are the minimum. Interactive examples are what make documentation genuinely useful. There are three levels of interactivity, and a great documentation site uses all of them.

Level 1: Live preview with code. The developer sees the rendered component alongside the code that produces it. Editing the code updates the preview in real time.

// Using Storybook as the backbone for interactive examples
 
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
 
const meta: Meta<typeof Button> = {
  title: 'Components/Button',
  component: Button,
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'ghost', 'danger'],
      description: 'The visual style of the button',
      table: {
        defaultValue: { summary: 'primary' },
        type: { summary: "'primary' | 'secondary' | 'ghost' | 'danger'" },
      },
    },
    size: {
      control: 'select',
      options: ['sm', 'md', 'lg'],
      description: 'The size of the button',
      table: {
        defaultValue: { summary: 'md' },
      },
    },
    isLoading: {
      control: 'boolean',
      description: 'Shows a loading spinner and disables the button',
    },
    disabled: {
      control: 'boolean',
      description: 'Disables the button',
    },
    children: {
      control: 'text',
      description: 'The button label',
    },
  },
  args: {
    children: 'Button',
    variant: 'primary',
    size: 'md',
  },
};
 
export default meta;
type Story = StoryObj<typeof Button>;
 
export const Playground: Story = {};
 
export const Variants: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
      <Button variant="primary">Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="danger">Danger</Button>
    </div>
  ),
};
 
export const Sizes: Story = {
  render: () => (
    <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  ),
};

Level 2: Controls panel. Storybook's controls addon lets developers tweak every prop and see the result immediately. This is far more efficient than reading a prop table and imagining the result.

Level 3: Copy-paste recipes. For every common use case, provide a complete, working code block that developers can paste into their project with minimal modification:

// Recipe: Form with validation feedback
import { Stack, Input, Button, Alert } from '@messier/core';
import { useState } from 'react';
 
interface FormData {
  email: string;
  password: string;
}
 
interface FormErrors {
  email?: string;
  password?: string;
}
 
function LoginForm() {
  const [data, setData] = useState<FormData>({ email: '', password: '' });
  const [errors, setErrors] = useState<FormErrors>({});
  const [submitError, setSubmitError] = useState<string | null>(null);
 
  const validate = (): boolean => {
    const newErrors: FormErrors = {};
    if (!data.email) newErrors.email = 'Email is required';
    if (!data.password) newErrors.password = 'Password is required';
    if (data.password.length < 8) newErrors.password = 'Password must be at least 8 characters';
    setErrors(newErrors);
    return Object.keys(newErrors).length === 0;
  };
 
  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    setSubmitError(null);
    if (!validate()) return;
 
    try {
      // await api.login(data);
    } catch {
      setSubmitError('Invalid email or password');
    }
  };
 
  return (
    <form onSubmit={handleSubmit}>
      <Stack gap="md">
        {submitError && <Alert variant="error">{submitError}</Alert>}
        <Input
          label="Email"
          type="email"
          value={data.email}
          onChange={(e) => setData({ ...data, email: e.target.value })}
          error={errors.email}
        />
        <Input
          label="Password"
          type="password"
          value={data.password}
          onChange={(e) => setData({ ...data, password: e.target.value })}
          error={errors.password}
        />
        <Button type="submit" variant="primary">
          Sign In
        </Button>
      </Stack>
    </form>
  );
}

Auto-Generated API References

Prop tables should never be written by hand. They should be generated from your TypeScript interfaces. This guarantees accuracy and eliminates the documentation rot problem entirely.

Storybook's react-docgen-typescript plugin extracts prop information from your component interfaces automatically. But for a custom documentation site, you can use the TypeScript compiler API directly:

// scripts/generate-api-docs.ts
import ts from 'typescript';
import fs from 'fs';
import path from 'path';
 
interface PropDoc {
  name: string;
  type: string;
  required: boolean;
  defaultValue: string | null;
  description: string;
}
 
function extractProps(filePath: string, componentName: string): PropDoc[] {
  const program = ts.createProgram([filePath], {
    jsx: ts.JsxEmit.React,
    strict: true,
  });
 
  const checker = program.getTypeChecker();
  const sourceFile = program.getSourceFile(filePath);
  if (!sourceFile) return [];
 
  const props: PropDoc[] = [];
 
  ts.forEachChild(sourceFile, (node) => {
    if (ts.isInterfaceDeclaration(node) && node.name.text === `${componentName}Props`) {
      for (const member of node.members) {
        if (ts.isPropertySignature(member) && member.name) {
          const name = member.name.getText(sourceFile);
          const type = checker.typeToString(
            checker.getTypeAtLocation(member),
            member,
            ts.TypeFormatFlags.NoTruncation
          );
          const required = !member.questionToken;
          const jsDoc = ts.getJSDocTags(member);
          const description = ts.getJSDocCommentsAndTags(member)
            .map((tag) => (typeof tag.comment === 'string' ? tag.comment : ''))
            .join(' ');
          const defaultTag = jsDoc.find((tag) => tag.tagName.text === 'default');
          const defaultValue = defaultTag
            ? typeof defaultTag.comment === 'string'
              ? defaultTag.comment
              : null
            : null;
 
          props.push({ name, type, required, defaultValue, description });
        }
      }
    }
  });
 
  return props;
}
 
// Generate markdown tables for each component
const componentsDir = path.resolve(__dirname, '../packages/core/src/components');
const entries = fs.readdirSync(componentsDir, { withFileTypes: true });
 
for (const entry of entries) {
  if (!entry.isDirectory()) continue;
  const componentFile = path.join(componentsDir, entry.name, `${entry.name}.tsx`);
  if (!fs.existsSync(componentFile)) continue;
 
  const props = extractProps(componentFile, entry.name);
  if (props.length === 0) continue;
 
  let markdown = `## ${entry.name} Props\n\n`;
  markdown += '| Prop | Type | Required | Default | Description |\n';
  markdown += '|------|------|----------|---------|-------------|\n';
 
  for (const prop of props) {
    markdown += `| \`${prop.name}\` | \`${prop.type}\` | ${prop.required ? 'Yes' : 'No'} | ${
      prop.defaultValue ? `\`${prop.defaultValue}\`` : '-'
    } | ${prop.description} |\n`;
  }
 
  const outputPath = path.join(__dirname, '../docs/api', `${entry.name}.md`);
  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
  fs.writeFileSync(outputPath, markdown);
}

Run this script as part of your build pipeline. Every time a component's TypeScript interface changes, the API documentation updates automatically.

Writing Guidelines That Actually Guide

Beyond API references, design system documentation needs guidelines — when to use one component versus another, which variant is appropriate for which context, and common patterns to follow.

Write guidelines in a scannable format. Use do/don't pairs, short bullet points, and visual examples:

## Button Guidelines
 
### When to use
- For primary actions that submit forms or trigger state changes
- For navigation to important destinations (use `as="a"`)
- For secondary actions within a group of related actions
 
### When not to use
- For navigation within the app — use Link instead
- For toggling a boolean state — use Switch instead
- For actions within a sentence of text — use TextButton instead
 
### Variant selection
- **Primary**: One per screen for the most important action
- **Secondary**: For supporting actions alongside a primary button
- **Ghost**: For tertiary actions, especially in toolbars or dense layouts
- **Danger**: For destructive actions (delete, remove, revoke)
 
### Sizing
- **Small (sm)**: Dense interfaces like tables, inline actions
- **Medium (md)**: Default for most use cases
- **Large (lg)**: Marketing pages, onboarding flows, mobile touch targets

These guidelines should be on the same page as the interactive examples — not in a separate "design guidelines" section that nobody navigates to.

Sustainable Documentation Workflows

Documentation that requires heroic effort to maintain will not be maintained. Build workflows that make documentation updates a natural byproduct of development.

Co-locate documentation with components. The stories, examples, and guidelines for a Button should live in the Button directory. When a developer updates the Button component, the documentation is right there — visible in the same pull request diff.

Require documentation in the PR checklist. Your pull request template should include "Documentation updated" as a checkbox. Code reviewers should verify that new props are documented, new examples are added for new features, and deprecated patterns are updated.

Test your documentation. Code examples in documentation should be compiled and type-checked. A TypeScript example that does not type-check is documentation that teaches developers the wrong thing.

// scripts/test-docs-examples.ts
// Extract code blocks from MDX files and type-check them
 
import fs from 'fs';
import path from 'path';
import ts from 'typescript';
 
function extractCodeBlocks(mdxContent: string): string[] {
  const regex = /```tsx?\n([\s\S]*?)```/g;
  const blocks: string[] = [];
  let match;
  while ((match = regex.exec(mdxContent)) !== null) {
    blocks.push(match[1]);
  }
  return blocks;
}
 
const docsDir = path.resolve(__dirname, '../docs');
const mdxFiles = fs.readdirSync(docsDir, { recursive: true })
  .filter((f) => String(f).endsWith('.mdx'));
 
let errors = 0;
 
for (const file of mdxFiles) {
  const content = fs.readFileSync(path.join(docsDir, String(file)), 'utf-8');
  const blocks = extractCodeBlocks(content);
 
  for (let i = 0; i < blocks.length; i++) {
    const tempFile = path.join(__dirname, `__temp_doc_${i}.tsx`);
    // Wrap in a module context
    const wrappedCode = `
      import React from 'react';
      import { Button, Input, Card, Stack, Alert, Modal } from '@messier/core';
      ${blocks[i]}
    `;
    fs.writeFileSync(tempFile, wrappedCode);
 
    const program = ts.createProgram([tempFile], {
      strict: true,
      jsx: ts.JsxEmit.ReactJSX,
      noEmit: true,
      skipLibCheck: true,
    });
 
    const diagnostics = ts.getPreEmitDiagnostics(program);
    if (diagnostics.length > 0) {
      console.error(`Type errors in ${file}, code block ${i + 1}:`);
      for (const diagnostic of diagnostics) {
        console.error(`  ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`);
      }
      errors++;
    }
 
    fs.unlinkSync(tempFile);
  }
}
 
if (errors > 0) {
  console.error(`\n${errors} documentation code block(s) have type errors.`);
  process.exit(1);
}

Run documentation CI. Build your documentation site in CI on every PR. If the build breaks, the PR cannot merge. This catches broken links, invalid MDX, and rendering errors before they reach the published docs.

Search and Discoverability

The best documentation in the world is useless if developers cannot find the page they need. Invest in search.

Integrate a search solution like Algolia DocSearch or a local search index. Index not just page titles but also prop names, code examples, and guideline content. A developer searching for "loading spinner button" should land on the Button documentation page.

Add search-friendly metadata to every page:

// docs/components/button.mdx frontmatter
---
title: "Button"
description: "A versatile button component for actions and navigation"
keywords: ["button", "action", "submit", "link", "loading", "disabled", "click"]
category: "components"
status: "stable"
---

Provide a component index page that shows every component at a glance — name, status, brief description, and a thumbnail preview. This lets developers scan visually for the component they need.

Conclusion

Documentation is the user interface of your design system. It deserves the same design thinking, the same attention to user experience, and the same quality standards as the components themselves. Organize for tasks not taxonomy, make examples interactive and copy-pasteable, generate API references from source code to prevent rot, write scannable guidelines, and build workflows that make documentation updates automatic. When developers can find what they need in under a minute and have a working implementation in under five, your documentation is doing its job.

Related Articles

technical

Versioning and Publishing Component Libraries

A practical guide to versioning, releasing, and distributing TypeScript component libraries using semantic versioning, changesets, and automated CI/CD publishing pipelines.

10 min read
business

Measuring the ROI of a Design System

A practical framework for measuring the return on investment of a design system, covering efficiency metrics, quality improvements, consistency gains, and how to communicate value to stakeholders.

10 min read
technical

Testing Strategies for UI Component Libraries

A comprehensive testing strategy for design system component libraries, covering unit tests, interaction tests, visual regression tests, and accessibility audits in TypeScript.

9 min read