documentation

When to Use

• Writing or updating README.md files
• Creating API reference documentation
• Writing user guides, tutorials, or how-to docs
• Documenting architecture or design decisions
• Creating CONTRIBUTING.md or other project docs

Document Structure by Type

README.md

# Project Name

Brief description (1-2 sentences).

## Features

- Key feature 1
- Key feature 2

## Quick Start

\`\`\`bash
# Installation
npm install project-name

# Usage
npx project-name
\`\`\`

## Documentation

Link to full docs if available.

## Contributing

Link to CONTRIBUTING.md or brief instructions.

## License

License type with link.

API Documentation

# API Reference

## Overview

Brief description of the API.

## Authentication

How to authenticate (if applicable).

## Endpoints

### `GET /resource`

Description of what this endpoint does.

**Parameters:**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | Resource identifier |

**Response:**

\`\`\`json
{
  "id": "123",
  "name": "Example"
}
\`\`\`

**Errors:**

| Code | Description |
|------|-------------|
| 404 | Resource not found |

User Guide

# Guide Title

## Overview

What this guide covers and prerequisites.

## Step 1: First Step

Clear instructions with code examples.

## Step 2: Second Step

Continue with logical progression.

## Troubleshooting

Common issues and solutions.

## Next Steps

Links to related guides or advanced topics.

Writing Principles

Clarity

Structure

Audience

Code Examples

Good Example

# Install the package
pip install mypackage

# Import and use
from mypackage import Client

client = Client(api_key="your-key")
result = client.get_data()
print(result)

Bad Example

# This is a comprehensive example showing all the features
# of the package including advanced configuration options
# and error handling patterns that you might need...
from mypackage import Client, Config, ErrorHandler
# ... 50 more lines

Key Rule: Examples should be minimal and focused. Show one concept at a time.

Formatting Guidelines

Headers

• Use sentence case: "Getting started" not "Getting Started"
• Maximum 3 levels deep (##, ###, ####)
• Headers should be descriptive and scannable

Code Blocks

• Always specify language for syntax highlighting
• Keep examples short (< 20 lines ideally)
• Include comments only when necessary

Tables

Use tables for:

• Parameter/option descriptions
• Feature comparisons
• Reference data

Links

• Use descriptive link text: "See the installation guide"
• Not: "Click here"

Checklist Before Submitting

• Title clearly describes the content
• Structure matches the document type
• Code examples are tested and work
• No spelling or grammar errors
• Links are valid
• Appropriate for target audience
• Follows project conventions (if any)