From core
Generates or updates documentation for code, APIs, or systems including READMEs, API references, inline comments, technical guides, and ADRs.
npx claudepluginhub thebushidocollective/han --plugin coreThis skill is limited to using the following tools:
Create clear, useful documentation that helps people understand and use your code.
Provides templates and best practices for writing README files, API documentation, user guides, changelogs, architecture docs, and inline code comments.
Writes READMEs, API references, architecture docs, user guides, and inline comments for codebases, libraries, CLIs, APIs. Audits docs for accuracy, clarity, completeness.
Creates READMEs, API docs, code comments, and architecture documentation with best practices, checklists, and Mermaid diagrams. Useful for doc writing, README creation, or code documentation requests.
Share bugs, ideas, or general feedback.
Create clear, useful documentation that helps people understand and use your code.
Write for the reader, not for yourself.
han-core:document - Generate or update documentation for code, APIs, or systems
/document [arguments]
Purpose: Help users understand what the project does and how to use it
Audience: New users, potential contributors
Key sections:
Purpose: Help developers use your API correctly
Audience: Other developers integrating with your code
Key information:
Purpose: Explain non-obvious decisions and complex logic
Audience: Future developers (including future you)
When to add:
Purpose: Teach how to accomplish specific tasks
Audience: Developers working with the system
Types:
Purpose: Document important technical decisions and their rationale
Audience: Current and future team members
Key information:
Good documentation:
Bad documentation:
# Project Name
Brief description (one paragraph) of what this project does and why it exists.
## Features
- Feature 1
- Feature 2
- Feature 3
## Installation
```bash
npm install project-name
import { Thing } from 'project-name'
const thing = new Thing()
thing.doSomething()
// Output: ...
[Most common use case with complete example]
[More complex scenarios]
functionName(param1, param2)Description of what the function does.
Parameters:
param1 (string, required): Description of parameterparam2 (number, optional): Description with default. Default: 42Returns: string - Description of return value
Throws:
Error - When parameter is invalidExample:
const result = functionName('hello', 10)
console.log(result) // "hello repeated 10 times"
[How to configure, if applicable]
Cause: Package not installed Solution:
npm install project-name
We welcome contributions! Please see CONTRIBUTING.md for details.
MIT License - see LICENSE file for details.
## API Documentation Template
### REST API
```markdown
## POST /api/users
Create a new user account.
### Authentication
Requires admin access token in Authorization header.
### Request
**Headers:**
```json
{
"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".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
}
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"
X-RateLimit-Remaining header
### Function/Method Documentation
```typescript
/**
* 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...
}
DO comment:
DON'T comment:
// 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
}
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
# 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.
```bash
# Command to run
command --option value
Expected result: What you should see.
If something goes wrong: How to troubleshoot.
[Continue with clear steps...]
Complete working example showing the entire process.
// Full code example
Symptom: What you see when this happens. Cause: Why it happens. Solution: How to fix it.
## Architecture Decision Record Template
```markdown
# 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]
Different audiences need different docs:
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
Test your examples:
Documentation rots:
Avoid jargon:
Be specific:
Use active voice:
Bad: "Use the function to process data" Good: "Use processData(items) to validate and format user input"
Bad: Docs say version 1.0, code is version 3.0 Good: Update docs with code changes
Bad: "Simply configure the flux capacitor" Good: "Add FLUX_CAPACITOR=true to your .env file"
Bad:
const result = doSomething()
Good:
import { doSomething } from 'my-package'
const result = doSomething({
option1: 'value',
option2: 42
})
console.log(result) // Expected output
Bad: Document every single line Good: Document the "why" and non-obvious parts
When the user says:
Good documentation helps people use your code correctly and efficiently.