Standards documentation

Documentation Standards

Provides: README templates, API documentation patterns, code comment guidelines, and technical writing clarity principles.

Quick Reference

Golden Rule: If users ask the same question twice, document it

Document (✅ DO):

• WHY decisions were made
• Complex algorithms/logic
• Public APIs, setup, common use cases

Don't Document (❌ DON'T):

• Obvious code (i++ doesn't need comment)
• What code does (should be self-explanatory)

Principles: Audience-focused, Show don't tell, Keep current

---

Principles

Audience-focused: Write for users (what/how), developers (why/when), contributors (setup/conventions) Show, don't tell: Code examples, real use cases, expected output Keep current: Update with code changes, remove outdated info, mark deprecations

README Structure

# Project Name
Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
npm install package-name

Quick Start

const result = doSomething();

Usage

[Detailed examples]

API Reference

[If applicable]

Contributing

[Link to CONTRIBUTING.md]

License

[License type]

## Function Documentation

```javascript
/**
 * Calculate total price including tax
 * 
 * @param {number} price - Base price
 * @param {number} taxRate - Tax rate (0-1)
 * @returns {number} Total with tax
 * 
 * @example
 * calculateTotal(100, 0.1) // 110
 */
function calculateTotal(price, taxRate) {
  return price * (1 + taxRate);
}

What to Document

✅ DO

• WHY decisions were made
• Complex algorithms/logic
• Non-obvious behavior
• Public APIs
• Setup/installation
• Common use cases
• Known limitations
• Workarounds (with explanation)

❌ DON'T

• Obvious code (i++ doesn't need comment)
• What code does (should be self-explanatory)
• Redundant information
• Outdated/incorrect info

Comments

Good

// Calculate discount by tier (Bronze: 5%, Silver: 10%, Gold: 15%)
const discount = getDiscountByTier(customer.tier);

// HACK: API returns null instead of [], normalize it
const items = response.items || [];

// TODO: Use async/await when Node 18+ is minimum

Bad

// Increment i
i++;

// Get user
const user = getUser();

API Documentation

### POST /api/users
Create a new user

**Request:**
```json
{ "name": "John", "email": "[email protected]" }

Response:

{ "id": "123", "name": "John", "email": "[email protected]" }

Errors:

• 400 - Invalid input
• 409 - Email exists

## Best Practices

✅ Explain WHY, not just WHAT
✅ Include working examples
✅ Show expected output
✅ Cover error handling
✅ Use consistent terminology
✅ Keep structure predictable
✅ Update when code changes

**Golden Rule**: If users ask the same question twice, document it.