documentation-fundamentals

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

// ❌ 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?"

## What

A CLI tool that converts Figma designs to React components.

2. Why Does It Exist?

"What pain point motivated this project?"

## 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."

## Installation

npm install your-package

4. How to Use

"The simplest possible example that works."

## Quick Start

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

5. How to Contribute (Optional)

"For open source projects."

## 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)

/**
 * 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
}