documentation-fundamentals

What this skill does

# Documentation Fundamentals Review

> "Code tells you HOW, comments tell you WHY. If you only explain what the code does, you're wasting everyone's time."

## When to Apply

Activate this skill when:
- Reviewing or creating README files
- Writing JSDoc/docstring comments
- Inline code comments
- API documentation
- Architecture decision records

---

## The Golden Rule: WHY, Not WHAT

```typescript
// ❌ BAD: Explains what (code already says this)
// Increment counter by 1
counter++;

// ✅ GOOD: Explains why (context the code can't provide)
// Counter must be incremented before validation runs
// to account for the edge case where initial value is 0
counter++;
```

---

## README Structure (The 5 Essentials)

Every README must answer these questions:

### 1. What Is This? (1 sentence)

> "What problem does this solve in one sentence?"

```markdown
## What

A CLI tool that converts Figma designs to React components.
```

### 2. Why Does It Exist?

> "What pain point motivated this project?"

```markdown
## Why

Manually converting designs to code takes hours and introduces inconsistencies.
This tool automates the process, ensuring pixel-perfect components.
```

### 3. How to Install

> "Copy-paste instructions that work."

```markdown
## Installation

npm install your-package
```

### 4. How to Use

> "The simplest possible example that works."

```markdown
## Quick Start

npx your-tool --input design.fig --output ./components
```

### 5. How to Contribute (Optional)

> "For open source projects."

```markdown
## Contributing

1. Fork the repo
2. Create your feature branch
3. Submit a pull request
```

---

## Comment Types & When to Use Them

### Function/Method Documentation (JSDoc)

```typescript
/**
 * Validates email format and checks domain against blocklist.
 *
 * @param email - The email address to validate
 * @returns ValidationResult with success status and error message
 *
 * @example
 * const result = validateEmail('[email protected]');
 * if (!result.success) {
 *   showError(result.error);
 * }
 *
 * Note: This uses the RFC 5322 regex pattern, which is intentionally
 * strict to prevent disposable email addresses.
 */
function validateEmail(email: string): ValidationResult {
  // Implementation
}
```

### Inline Comments (Only for WHY)

```typescript
// Rate limit is 100/min but we use 80 to leave headroom for retries
const RATE_LIMIT = 80;

// Sort descending because newest items should appear first
// (business requirement from PM - see ticket #1234)
items.sort((a, b) => b.date - a.date);

// HACK: API returns dates as strings, need to parse manually
// TODO: Remove after backend migration (Q2 2026)
const date = new Date(response.dateString);
```

### Block Comments (Complex Logic)

```typescript
/*
 * Authentication Flow:
 * 1. Check local token cache
 * 2. If expired, attempt silent refresh
 * 3. If refresh fails, redirect to login
 *
 * We use refresh tokens instead of re-authentication to avoid
 * disrupting the user experience during long sessions.
 */
```

---

## Common Mistakes (Anti-Patterns)

### 1. Commenting the Obvious

```typescript
// ❌ BAD: Useless comment
// Set name to "John"
const name = "John";

// Get the user's age
const age = user.age;

// Loop through items
for (const item of items) { ... }

// ✅ GOOD: No comment needed (code is self-explanatory)
const name = "John";
```

### 2. Outdated Comments

```typescript
// ❌ BAD: Comment doesn't match code (dangerous!)
// Filter out inactive users
const users = data.filter(u => u.role === 'admin');

// ✅ GOOD: Comment matches reality
// Only show admin users in management view
const users = data.filter(u => u.role === 'admin');
```

### 3. No Context on Magic Numbers

```typescript
// ❌ BAD: What is 86400?
const expiresIn = 86400;

// ✅ GOOD: Explains the magic
const SECONDS_PER_DAY = 86400;
const expiresIn = SECONDS_PER_DAY; // Tokens expire after 24 hours
```

### 4. Commented-Out Code

```typescript
// ❌ BAD: Dead code polluting the file
// const oldImplementation = () => { ... };
// function deprecatedHelper() { ... }

// ✅ GOOD: Delete it! Git remembers everything
```

### 5. Empty README

```markdown
<!-- ❌ BAD: Auto-generated, never updated -->
# my-project

This project was bootstrapped with Create React App.
```

---

## Socratic Questions

Ask these instead of giving answers:

1. **WHY not WHAT**: "Does this comment tell me something the code doesn't?"
2. **Audience**: "Would a developer joining tomorrow understand this?"
3. **Maintenance**: "If you change the code, would you remember to update this comment?"
4. **README**: "Can someone run this project with just the README instructions?"
5. **JSDoc**: "What would a developer need to know to use this function correctly?"
6. **Necessity**: "If you delete this comment, is anything lost?"

---

## README Template

```markdown
# Project Name

One-sentence description of what this does.

## Why

The problem this solves and why it matters.

## Installation

npm install project-name

## Quick Start

Minimal code example that works.

## API

### functionName(param)

Description of what it does.

**Parameters:**
- `param` (string): What this parameter is for

**Returns:** What gets returned

**Example:**
```js
// Usage example
```

## Configuration

Available options and their defaults.

## Contributing

How to contribute (if applicable).

## License

MIT (or your license)
```

---

## JSDoc Essentials

```typescript
/**
 * Brief description of what this function does.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this error occurs
 * @example
 * // Show how to use it
 * const result = myFunction('input');
 *
 * @see RelatedFunction for similar functionality
 * @deprecated Use newFunction instead (v2.0+)
 */
```

---

## Red Flags to Call Out

| Flag | Question |
|------|----------|
| Empty README | "Can a new developer run this project right now?" |
| `// Set x to 5` | "Does this comment add value? The code already says this." |
| Outdated comments | "Does this comment still match what the code does?" |
| No JSDoc on exports | "How would someone know how to use this function?" |
| Commented-out code | "Why is this here? Git has history if you need it back." |
| Magic numbers | "What does 3600 mean? Why this number?" |

---

## Interview Connection

> "I maintain comprehensive documentation including READMEs, JSDoc comments, and architecture decision records, ensuring code is maintainable by the entire team."

Documentation habits demonstrate:
- Communication skills
- Long-term thinking
- Team player mentality
- Senior-level maturity

---

## MCP Usage

### Context7 - Framework Docs
```
Fetch: JSDoc documentation
Fetch: Markdown best practices
```

### Octocode - Real Examples
```
Search: README.md patterns in popular repos
Search: JSDoc examples in TypeScript projects
```