codebase-documenter

Files (10)

• SKILL.md
• _meta.json
• API.template.md · assets/templates/
• ARCHITECTURE.template.md · assets/templates/
• CODE_COMMENTS.template.md · assets/templates/
• README.template.md · assets/templates/
• index.js
• package.json
• documentation_guidelines.md · references/
• visual_aids_guide.md · references/

SKILL.md (first lines)

# Codebase Documenter

## Overview

This skill enables creating comprehensive, beginner-friendly documentation for codebases. It provides structured templates and best practices for writing READMEs, architecture guides, code comments, and API documentation that help new users quickly understand and contribute to projects.

## Core Principles for Beginner-Friendly Documentation

When documenting code for new users, follow these fundamental principles:

1. **Start with the "Why"** - Explain the purpose before diving into implementation details
2. **Use Progressive Disclosure** - Present information in layers from simple to complex
3. **Provide Context** - Explain not just what the code does, but why it exists
4. **Include Examples** - Show concrete usage examples for every concept
5. **Assume No Prior Knowledge** - Define terms and avoid jargon when possible
6. **Visual Aids** - Use diagrams, flowcharts, and file tree structures
7. **Quick Wins** - Help users get something running within 5 minutes

## Documentation Types and When to Use Them

### 1. README Documentation

**When to create:** For project root directories, major feature modules, or standalone components.

**Structure to follow:**
```markdown
# Project Name

## What This Does
[1-2 sentence plain-English explanation]

## Quick Start
[Get users running the project in < 5 minutes]

## Project Structure
[Visual file tree with explanations]

## Key Concepts
[Core concepts users need to understand]

## Common Tasks
[Step-by-step guides for frequent operations]

## Troubleshooting
[Common issues and solutions]
```

**Best practices:**
- Lead with the project's value proposition
- Include setup instructions that actually work (test them!)
- Provide a visual overview of the project structure
- Link to deeper documentation for advanced topics
- Keep the root README focused on getting started

### 2. Architecture Documentation

**When to create:** For projects with multiple modules, complex data flows, or non-obvious design decisions.

**Structure to follow:**
```markdown
# Architecture Overview

## System Design
[High-level diagram and explanation]

## Directory Structure
[Detailed breakdown with purpose of each directory]

## Data Flow
[How data moves through the system]

## Key Design Decisions
[Why certain architectural choices were made]

## Module Dependencies
[How different parts interact]

## Extension Points
[Where and how to add new features]
```

**Best practices:**
- Use diagrams to show system components and relationships
- Explain the "why" behind architectural decisions
- Document both the happy path and error handling
- Identify boundaries between modules
- Include visual file tree structures with annotations

### 3. Code Comments

**When to create:** For complex logic, non-obvious algorithms, or code that requires context.

**Annotation patterns:**

**Function/Method Documentation:**
```javascript
/**
 * Calculates the prorated subscription cost for a partial billing period.
 *
 * Why this exists: Users can subscribe mid-month, so we need to charge
 * them only for the days remaining in the current billing cycle.
 *
 * @param {number} fullPrice - The normal monthly subscription price
 * @param {Date} startDate - When the user's subscription begins
 * @param {Date} periodEnd - End of the current billing period
 * @returns {number} The prorated amount to charge
 *
 * @example
 * // User subscribes on Jan 15, period ends Jan 31
 * calculateProratedCost(30, new Date('2024-01-15'), new Date('2024-01-31'))
 * // Returns: 16.13 (17 days out of 31 days)
 */
```

**Complex Logic Documentation:**
```python
# Why this check exists: The API returns null for deleted users,
# but empty string for users who never set a name. We need to
# distinguish between these cases for the audit log.

From 1337hero/claude-toolkit, WTFPL.

More from 1337hero/claude-toolkit