docs

Documentation Standards

1. README Structure

Essential Sections

# Project Name
Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Quick Start
### Installation
### Basic Usage

## Documentation
Link to full docs

## Contributing
How to contribute

## License
MIT / etc.

Optional Sections

• Screenshots/Demo
• Prerequisites
• Configuration
• Examples
• FAQ
• Changelog

2. API Documentation

Endpoint Format

## Endpoint Name

`METHOD /path/to/endpoint`

Brief description of what it does.

### Parameters

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

### Request
```json
{
  "field": "value"
}

Response

{
  "success": true,
  "data": {}
}

Errors

Code	Description
400	Invalid input
401	Unauthorized

## 3. Code Comments

### JSDoc/TSDoc Format
```typescript
/**
 * Brief description of the function.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this happens
 * @example
 * ```ts
 * const result = functionName('value')
 * ```
 */
function functionName(paramName: string): ReturnType {
  // implementation
}

When to Comment

• Complex algorithms
• Non-obvious decisions
• Workarounds and hacks
• Public APIs
• Gotchas and edge cases

When NOT to Comment

• Self-explanatory code
• What the code does (focus on why)
• Redundant type information
• Obvious operations

4. Tutorial Structure

Sections

1. Overview - What you'll learn
2. Prerequisites - What you need
3. Step-by-step guide - Numbered steps
4. Complete example - Full working code
5. Next steps - Where to go from here

Writing Tips

• One concept per step
• Show, don't just tell
• Anticipate errors
• Provide checkpoints
• Link to references

5. Architecture Documentation

System Overview

# Architecture

## High-Level Design
Diagram or description of main components

## Components
### Component A
- Responsibility
- Dependencies
- Key interfaces

## Data Flow
How data moves through the system

## Key Decisions
### Decision 1
- Context
- Options considered
- Chosen solution
- Rationale