documentation（文档）

Documentation Skill

Create clear, useful documentation that helps people understand and use your code.

Core Principle

Write for the reader, not for yourself.

Types of Documentation

1. README Files

Purpose: Help users understand what the project does and how to use it

Audience: New users, potential contributors

Key sections:

• What it does (one paragraph)
• Installation instructions
• Quick start example
• Common use cases
• Link to full documentation
• How to contribute
• License

2. API Documentation

Purpose: Help developers use your API correctly

Audience: Other developers integrating with your code

Key information:

• Endpoint/function signature
• Parameters and types
• Return values
• Error cases
• Authentication requirements
• Examples

3. Inline Comments

Purpose: Explain non-obvious decisions and complex logic

Audience: Future developers (including future you)

When to add:

• Non-obvious decisions ("why" not "what")
• Complex algorithms
• Workarounds
• Edge cases
• Performance considerations
• Security considerations

4. Technical Guides

Purpose: Teach how to accomplish specific tasks

Audience: Developers working with the system

Types:

• How-to guides (step-by-step)
• Architecture overviews (system structure)
• Integration guides (connecting systems)
• Troubleshooting guides (debugging help)

5. Architecture Decision Records (ADRs)

Purpose: Document important technical decisions and their rationale

Audience: Current and future team members

Key information:

• Context (what problem exists)
• Decision (what was chosen)
• Alternatives considered
• Consequences (trade-offs)

README Template

# Project Name

Brief description (one paragraph) of what this project does and why it exists.

## Features

- Feature 1
- Feature 2
- Feature 3

## Installation

npm install project-name

## Quick Start

import { Thing } from 'project-name'

const thing = new Thing() thing.doSomething() // Output: ...

## Usage

### Basic Usage

[Most common use case with complete example]

### Advanced Usage

[More complex scenarios]

## API Reference

### `functionName(param1, param2)`

Description of what the function does.

**Parameters:**

- `param1` (string, required): Description of parameter
- `param2` (number, optional): Description with default. Default: 42

**Returns:** `string` - Description of return value

**Throws:**

- `Error` - When parameter is invalid

**Example:**

const result = functionName('hello', 10) console.log(result) // "hello repeated 10 times"

## Configuration

[How to configure, if applicable]

## Troubleshooting

### Error: "Cannot find module"

**Cause:** Package not installed **Solution:**

npm install project-name

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](https://github.com/thebushidocollective/han/blob/HEAD/plugins/core/skills/documentation/CONTRIBUTING.md) for details.

## License

MIT License - see [LICENSE](https://github.com/thebushidocollective/han/blob/HEAD/plugins/core/skills/documentation/LICENSE) file for details.

API Documentation Template

REST API

## POST /api/users

Create a new user account.

### Authentication

Requires admin access token in Authorization header.

### Request

**Headers:**

{ "Content-Type": "application/json", "Authorization": "Bearer <admin_token>" }

**Body:**

{ "email": "user@example.com", "name": "John Doe", "role": "user" }

**Body Parameters:**

- `email` (string, required): Valid email address. Must be unique.
- `name` (string, required): User's full name. 2-100 characters.
- `role` (string, optional): User role. One of: "user", "admin". Default: "user".

### Response

**Success (201 Created):**

{ "id": "abc123", "email": "user@example.com", "name": "John Doe", "role": "user", "createdAt": "2024-01-01T00:00:00Z" }

**Error Responses:**

**400 Bad Request:**

{ "error": "Invalid email format", "field": "email" }

**401 Unauthorized:**

{ "error": "Authentication required" }

**403 Forbidden:**

{ "error": "Admin access required" }

**409 Conflict:**

{ "error": "Email already exists", "field": "email" }

**429 Too Many Requests:**

{ "error": "Rate limit exceeded. Try again in 60 seconds.", "retryAfter": 60 }

### Example

**cURL:**

curl -X POST https://api.example.com/users \ -H "Content-Type: application/json" \ -H "Authorization: Bearer abc123..." \ -d '{ "email": "user@example.com", "name": "John Doe", "role": "user" }'

**JavaScript:**

const response = await fetch('https://api.example.com/users', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer abc123...' }, body: JSON.stringify({ email: 'user@example.com', name: 'John Doe', role: 'user' }) })

const user = await response.json() console.log(user.id) // "abc123"

### Rate Limiting

- 100 requests per minute per API key
- Returns 429 when exceeded
- Check `X-RateLimit-Remaining` header

Function/Method Documentation

/**
 * Calculate the total price including tax and shipping.
 *
 * Tax is calculated on the subtotal, not including shipping.
 * Free shipping is applied for orders over $50.
 *
 * @param items - Array of cart items with price and quantity
 * @param shippingAddress - Shipping address for tax calculation
 * @returns Object containing subtotal, tax, shipping, and total
 *
 * @throws {Error} If items array is empty
 * @throws {Error} If any item has invalid price or quantity
 *
 * @example
 * ```typescript
 * const total = calculateTotal([
 *   { price: 10, quantity: 2 },
 *   { price: 15, quantity: 1 }
 * ], { state: 'CA' })
 *
 * console.log(total)
 * // {
 * //   subtotal: 35,
 * //   tax: 2.80,
 * //   shipping: 0,
 * //   total: 37.80
 * // }
 * ```
 */
function calculateTotal(
  items: CartItem[],
  shippingAddress: Address
): OrderTotal {
  // Implementation...
}

Inline Comment Guidelines

When to Comment

✅ DO comment:

• Why: Explains reasoning for non-obvious decisions
• Trade-offs: Documents deliberate choices
• Workarounds: Explains temporary solutions
• Complex logic: Clarifies difficult algorithms
• Edge cases: Documents special handling
• Performance: Explains optimization choices
• Security: Notes security considerations

❌ DON'T comment:

• What: Code is self-explanatory
• Redundant: Comment repeats code
• Obvious: Anyone can see what it does

Good vs Bad Comments

// ❌ BAD: States the obvious
// Loop through users
for (const user of users) {
  // Print user name
  console.log(user.name)
}

// ✅ GOOD: Explains why
// Process in creation order to maintain referential integrity
// (newer records may reference older ones)
for (const user of users.sort((a, b) => a.createdAt - b.createdAt)) {
  processUser(user)
}

// ❌ BAD: Redundant
// Add 1 to counter
counter = counter + 1

// ✅ GOOD: Explains non-obvious decision
// +1 offset because API uses 1-based indexing (not 0-based)
const pageNumber = index + 1

// ❌ BAD: Explains what (obvious)
function calculateTotal(price, quantity) {
  // Multiply price by quantity
  return price * quantity
}

// ✅ GOOD: Explains why (non-obvious)
function calculateTotal(price, quantity) {
  // Use Number.toFixed(2) to prevent floating point errors
  // (0.1 + 0.2 !== 0.3 in JavaScript)
  return Number((price * quantity).toFixed(2))
}

// ❌ BAD: Commented-out code
function processOrder(order) {
  // const tax = order.subtotal * 0.08
  const tax = calculateTax(order)
  return order.subtotal + tax
}

// ✅ GOOD: Explains temporary workaround
function processOrder(order) {
  // TODO: Remove when new tax API is deployed (JIRA-123)
  // Using hardcoded rate temporarily during migration
  const tax = order.subtotal * 0.08
  return order.subtotal + tax
}

Comment Formats

Single-line comments:

// For brief explanations
const tax = subtotal * TAX_RATE  // Updated quarterly

Multi-line comments:

/*
 * For longer explanations that span multiple lines.
 * Use when context requires more detail.
 */

Doc comments (JSDoc/TSDoc):

/**
 * For API documentation.
 * Parsed by documentation generators.
 * @param name - Parameter description
 * @returns Return value description
 */

TODO comments:

// TODO(username): Description of what needs to be done
// FIXME: Description of what's broken and needs fixing
// HACK: Description of temporary workaround
// NOTE: Important information to highlight

Technical Guide Template

# How to [Task Name]

Brief description of what this guide teaches and who should use it.

## Prerequisites

- Requirement 1
- Requirement 2
- Knowledge/tools needed

## Overview

High-level explanation of the process or concept.

## Step-by-Step Instructions

### Step 1: [First Action]

Detailed description of what to do.

Command to run

command --option value

**Expected result:** What you should see.

**If something goes wrong:** How to troubleshoot.

### Step 2: [Next Action]

[Continue with clear steps...]

## Example

Complete working example showing the entire process.

// Full code example

## Common Issues

### Issue: [Problem Description]

**Symptom:** What you see when this happens. **Cause:** Why it happens. **Solution:** How to fix it.

## Related Documentation

- [Link to related guide]
- [Link to API docs]

## Next Steps

- [What to do after completing this guide]

Architecture Decision Record Template

# ADR-###: [Decision Title]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** YYYY-MM-DD
**Deciders:** [Names of decision makers]

## Context

What is the issue we're trying to solve? What factors are at play?
What constraints exist?

## Decision

What did we decide to do?

## Alternatives Considered

### Alternative 1: [Name]

**Description:** Brief explanation

**Pros:**
- Advantage 1
- Advantage 2

**Cons:**
- Disadvantage 1
- Disadvantage 2

**Why not chosen:** Explanation

### Alternative 2: [Name]

[Same structure...]

## Consequences

### Positive

- Benefit 1
- Benefit 2

### Negative

- Drawback 1
- Drawback 2

### Neutral

- Trade-off 1
- Trade-off 2

## Implementation Notes

Any specific guidance for implementing this decision.

## References

- [Related documentation]
- [Discussion links]
- [Research sources]

Documentation Best Practices

1. Write for Your Audience

Different audiences need different docs:

• New users: Quick start, common use cases
• API consumers: Complete reference, examples
• Contributors: Architecture, dev setup
• Maintainers: Design decisions, trade-offs

2. Show, Don't Just Tell

Bad:

The function accepts parameters and returns a result.

Good:

function calculateTotal(items, tax) {
  return items.reduce((sum, item) => sum + item.price, 0) * (1 + tax)
}

// Example usage:
const items = [{ price: 10 }, { price: 20 }]
const total = calculateTotal(items, 0.08) // 32.40

3. Keep Examples Runnable

Test your examples:

• Copy/paste should work
• Include all imports
• Show complete code, not fragments
• Verify examples actually run

4. Maintain Documentation

Documentation rots:

• Update docs when code changes
• Include doc updates in PRs
• Review docs periodically
• Mark outdated docs clearly

5. Use Clear Language

Avoid jargon:

• Bad: "Leverages polymorphic memoization"
• Good: "Caches results based on input type"

Be specific:

• Bad: "It's fast"
• Good: "Responds in < 100ms for 95% of requests"

Use active voice:

• Bad: "The request is processed by the server"
• Good: "The server processes the request"

Documentation Checklist

README

• Clear description of what project does
• Installation instructions
• Quick start example
• Link to full documentation
• How to contribute
• License information

API Docs

• All public APIs documented
• Parameters described with types
• Return values described
• Error cases documented
• Examples provided
• Authentication requirements stated

Inline Comments

• Complex logic explained
• Non-obvious decisions documented
• Workarounds noted
• No redundant comments
• No commented-out code
• TODOs have owner and context

Technical Guides

• Prerequisites listed
• Steps are clear and ordered
• Examples are complete and runnable
• Common issues addressed
• Related docs linked

Integration with Other Skills

• Use explainer skill for creating clear explanations
• Use proof-of-work skill to verify examples actually work
• Reference architecture-design skill for architecture documentation
• Reference technical-planning skill for implementation guides

Common Documentation Mistakes

❌ No Examples

Bad: "Use the function to process data" Good: "Use processData(items) to validate and format user input"

❌ Outdated Information

Bad: Docs say version 1.0, code is version 3.0 Good: Update docs with code changes

❌ Assuming Knowledge

Bad: "Simply configure the flux capacitor" Good: "Add FLUX_CAPACITOR=true to your.env file"

❌ Incomplete Examples

Bad:

const result = doSomething()

Good:

import { doSomething } from 'my-package'

const result = doSomething({
  option1: 'value',
  option2: 42
})
console.log(result) // Expected output

❌ Too Much Documentation

Bad: Document every single line Good: Document the "why" and non-obvious parts

Remember

1. Write for the reader - What do they need to know?
2. Show with examples - Working code is clearer than prose
3. Keep it updated - Stale docs are worse than no docs
4. Test examples - Verify they actually work
5. Explain "why" - The "what" is in the code

Good documentation helps people use your code correctly and efficiently.