Documentation

Good documentation makes a project easier to use, maintain, and contribute to. In React projects, documentation spans components, code, commits, and project-level files.

Component documentation

Storybook

Storybook is the recommended tool for documenting React components.It lets you preview components in isolation without needing to run the entire application, see all possible states, and generate interactive docs.

A “story” represents a single visual state of a component. For a simple example, let’s assume a simple Button component. The story will look like this.

import { Button } from './Button';

// The default export metadata for the component
export default {
  title: 'UI/Button',         // Title in the Storybook sidebar (use '/' for nesting)
  component: Button,          // The component itself
  tags: ['autodocs'],         // Enables automatic documentation generation
  argTypes: {                 // Controls for props in the Storybook UI
    backgroundColor: { control: 'color' },
  },
};

// Stories
export const Primary = {
  args: {
    primary: true,
    label: 'Button',
  },
};

export const Secondary = {
  args: {
    label: 'Button',
  },
};

export const Large = {
  args: {
    size: 'large',
    label: 'Button',
  },
};

export const Small = {
  args: {
    size: 'small',
    label: 'Button',
  },
};

By adding tags: ['autodocs'] to your default export, Storybook automatically creates a beautiful documentation page for your component. This page includes:

• The component title and description (from JSDoc).
• A live, interactive preview of the component.
• An ArgsTable (a props table) that lists all the component’s props, their types, default values, and descriptions (again, pulled from JSDoc or TypeScript types).
• Source code snippets for each story.

Code comments

Code commits

A frequently overlooked type of documentation is the commit message. We like to follow the best practices mentioned in the Conventional commit doc

• Format – type(scope): message
  
• Examples –
  
  • feat(auth): add Google login
    
  • fix(api): handle null response
    
  • docs(readme): update installation guide

Project documentation

There should be 3 main files documenting a project

README.md

The first place anyone will see when interacting with the project. Treat it like a front page for developers. A good README should have the following – 

• Project Title – What is the name of the project?
• Description – A clear, one-paragraph explanation of what the project does and what problem it solves.
• Key Features – A bulleted list of the main functionalities.
• Getting Started/Prerequisites – What software does a developer need to have installed (e.g., Node.js v18+, Docker, Python 3.10)?
• Installation & Running Locally – A copy-pasteable set of commands to get the project running on a local machine.
• Running Tests – The command to execute the test suite.
• Technology Stack – A brief list of the major technologies, frameworks, and libraries used.
• How to Contribute – A link to the CONTRIBUTING.md file.

CONTRIBUTING.md

This file explains the “rules of the road” for developers who want to contribute code.

• Pull Request (PR) Process – How to create a PR, what the required template looks like, and the review/approval process.
• Coding Standards – Link to your linter configuration (e.g., ESLint, Prettier) and any key style guides.
• Commit Message Guidelines – How to format commit messages (e.g., Conventional Commits).

CHANGELOG.md

A chronological log of user-facing changes for each version of the project. This is invaluable for both developers and stakeholders. Look at keepachangelog for a format to base the CHANGELOG on.

With these practices:

• Components are documented in isolation with Storybook.
• Code is supported by meaningful comments.
• Commits tell a clear story of changes.
• Project-level docs (README, CONTRIBUTING, CHANGELOG) ensure newcomers and contributors can onboard quickly.