Doc Writer

A comprehensive approach to creating clear, structured, and maintainable documentation. No shortcuts, no "later," no excuses.

FOUNDATIONAL PRINCIPLE: Documentation isn't optional overhead - it's an essential part of professional software development.

The Iron Law

No code ships without documentation. Period.

• No skipping docs because "code is self-documenting"
• No deferring docs because "we'll do it later"
• No accepting minimal scope because "that's what was asked"
• No assuming types or Swagger replace proper documentation

This is not negotiable. This is not flexible. This is mandatory.

When to Invoke

Invoke this skill when:

• Creating README files
• Writing API documentation
• Adding code comments
• Documenting components or functions
• Creating technical guides
• Writing contributing guidelines
• Documenting architecture decisions

NEVER skip this skill because:

• "Code is readable, docs aren't needed"
• "We'll document in the next sprint"
• "Nobody reads the documentation"
• "Manager said just a basic README"
• "TypeScript types are sufficient"

Documentation Types

1. README Documentation (MANDATORY for all projects)

Standard sections to include:

• Project Title & Description: What the project does (2-3 sentences)
• Features: Key capabilities (bullet points)
• Prerequisites: Required software/versions
• Installation: Step-by-step setup instructions
• Usage: How to run and use the project
• Configuration: Environment variables and settings
• Scripts: Available npm/pnpm commands
• Project Structure: Directory layout explanation
• Contributing: Guidelines for contributors
• License: License information

NO EXCUSES for incomplete README:

• ❌ "It's a simple project" → Simple projects still need setup instructions
• ❌ "Developers can figure it out" → Don't make them guess
• ❌ "Code is self-documenting" → README documents the PROJECT, not just code
• ❌ "Manager said basic only" → Advocate for completeness, then comply

2. API Documentation (MANDATORY for all endpoints)

For each API endpoint, document:

• Endpoint URL & Method: GET /api/users
• Description: What it does (1-2 sentences)
• Request Parameters: Query params, path params, body
• Request Headers: Required headers (Authorization, Content-Type, etc.)
• Response Format: Success and error responses (with examples)
• Examples: Request/response examples (curl, fetch, or language-specific)
• Error Codes: Possible errors and their meanings

NO EXCUSES for incomplete API docs:

• ❌ "Swagger auto-generates it" → Swagger provides basics, not comprehensive docs
• ❌ "Nobody reads API docs" → Developers DO read them when they need help
• ❌ "Types are sufficient" → Types show interface, not usage patterns
• ❌ "Too many endpoints" → Document complex ones at minimum

3. Code Comments (MANDATORY for complex logic)

Follow these principles:

• Explain why, not what (code shows what)
• Document complex algorithms and business logic
• Use JSDoc/TSDoc for functions:

/**
 * Fetches paginated user list with filtering
 * @param query - Query parameters for filtering and pagination
 * @returns Promise resolving to paginated user data
 * @throws {ApiError} When request fails or unauthorized
 * @example
 * // Fetch first page of active users
 * const users = await fetchUserList({ status: 'active', page: 1 });
 */
export async function fetchUserList(query?: UserQuery): Promise<PageResult<User>> {
  // Implementation
}

NO EXCUSES for missing comments on complex code:

• ❌ "Code is readable" → Readable code shows WHAT, not WHY
• ❌ "Self-documenting code" → Complex logic needs context
• ❌ "Time pressure" → 5 minutes of comments saves 30 minutes of confusion later
• ❌ "I'll add them later" → Later never comes

  小葱技能有更好的技能skills插件。

4. Component Documentation (MANDATORY for reusable components)

For Vue/React components, document:

• Purpose: What the component does (1 sentence)
• Props: All props with types, defaults, and descriptions
• Events: Emitted events with payloads
• Slots: Available slots and their purpose
• Usage Examples: How to use the component (2-3 examples)

Example:

## UserCard

Displays user information in a card format.

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| user | User | required | User object with name, email, avatar |
| showActions | boolean | false | Show edit/delete action buttons |
| size | 'sm' \| 'md' \| 'lg' | 'md' | Card size variant |

### Events

| Event | Payload | Description |
|-------|---------|-------------|
| edit | User | Emitted when edit button clicked |
| delete | string | Emitted when delete confirmed (userId) |

### Slots

| Slot | Description |
|------|-------------|
| header | Custom header content |
| footer | Custom footer content |

### Usage

```vue
<UserCard :user="currentUser" show-actions @edit="handleEdit" />

### 5. Architecture Documentation (MANDATORY for complex systems)

**Include:**
- **System Overview**: High-level architecture (ASCII diagram or Mermaid)
- **Technology Stack**: Frameworks, libraries, tools with versions
- **Data Flow**: How data moves through the system
- **Key Design Decisions**: Why certain choices were made (ADRs)
- **Directory Structure**: Project organization with explanations

## Documentation Standards

### Markdown Best Practices

```markdown
# Main Title (H1) - One per document

## Section (H2)

### Subsection (H3)

- **Bold** for emphasis on key terms
- `code` for inline code, commands, file names
- Use code blocks with language tags:

```typescript
const example: string = 'code block';

• Use tables for structured data:

• Use lists for steps or items
• Add links to related documentation

Language & Tone

• Use clear, concise language
• Write in present tense
• Address the reader directly (you)
• Avoid jargon unless necessary
• Provide examples for complex concepts

Code Examples

• Keep examples minimal but complete
• Show common use cases
• Include error handling examples
• Add comments to explain non-obvious parts

Documentation Templates

README Template

# Project Name

Brief description of what the project does (2-3 sentences).

## Features

- Feature 1
- Feature 2
- Feature 3

## Prerequisites

- Node.js >= 16
- pnpm >= 7

## Installation

```bash
pnpm install

Usage

pnpm dev

Configuration

Scripts

Project Structure

src/
├── api/          # API clients
├── components/   # Reusable components
├── views/        # Page components
└── stores/       # State management

Contributing

Please read CONTRIBUTING.md for details.

License

This project is licensed under the MIT License.

### API Endpoint Template

```markdown
## Endpoint Name

**Method**: `POST`
**URL**: `/api/resource`

### Description
What this endpoint does (1-2 sentences).

### Request Headers

| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer token |
| Content-Type | Yes | application/json |

### Request Body

```json
{
  "field": "value"
}

Response

Success (200):

{
  "code": 0,
  "data": {},
  "msg": "success"
}

Error (400):

{
  "code": 400,
  "msg": "Error message"
}

Example

curl -X POST https://api.example.com/resource \
  -H "Authorization: Bearer token" \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}'

## Red Flags - STOP AND DOCUMENT

**If you catch yourself thinking ANY of these, STOP immediately:**

- ❌ "Code is readable, skip documentation"
- ❌ "We'll document in the next sprint"
- ❌ "Nobody reads the docs anyway"
- ❌ "TypeScript types are sufficient documentation"
- ❌ "Swagger auto-generates enough"
- ❌ "Manager said basic README only"
- ❌ "Time pressure, skip docs"
- ❌ "Self-documenting code"
- ❌ "Examples are optional"
- ❌ "We can always add docs later"
- ❌ "Docs get outdated quickly, so skip them"
- ❌ "Auto-generated docs are sufficient"
- ❌ "Non-technical audience won't read technical docs"
- ❌ "Competitors might learn from our docs"
- ❌ "Documentation debt is too large to address"

**All of these mean: STOP. Write the documentation. No shortcuts.**

## Rationalization Counter-Table

| Excuse You Might Make | Why It's Wrong | What To Do Instead |
|----------------------|----------------|-------------------|
| "Code is self-documenting" | Readable code shows WHAT, not WHY. Complex logic needs context. | Add comments explaining WHY, not WHAT |
| "We'll document later" | Later never comes. Documentation compounds in value. | Document alongside code, not after |
| "Nobody reads docs" | Developers read docs when they need help. ROI is long-term. | Write for the developer who WILL need this |
| "Types are sufficient" | Types show interface, not usage patterns or common cases. | Add examples showing practical usage |
| "Swagger auto-generates" | Swagger provides basics, not comprehensive docs or examples. | Enhance Swagger with detailed explanations |
| "Manager said basic only" | Advocate for completeness. If overruled, comply but note gaps. | "I recommend X sections. If you prefer less, I'll do Y." |
| "Time pressure" | 5 min docs now saves 30 min confusion later. Docs have compound ROI. | Right-size docs, don't eliminate them |
| "Simple project" | Simple projects still need setup instructions and usage examples. | Document basics: install, configure, use |
| "Examples are optional" | Examples show practical usage. Types alone are academic. | At minimum: 1 example per public API |
| "Docs get outdated" | Volatile systems need docs too. Make them maintainable, not static. | Living documentation: modular, automated, update with PRs |
| "Auto-generated enough" | Auto-generated shows signatures, not usage patterns or guides. | Add manual layer: examples, tutorials, common patterns |
| "Non-technical audience" | Different audiences need different docs, not less documentation. | Create both: executive summary + technical docs |
| "Competitors will learn" | Open-source advantage is execution, not secrecy. Better docs = more adoption. | Document comprehensively. Attract community, not hide from competitors |
| "Documentation debt" | Large debt is addressed incrementally, not with big-bang projects. | Document as you touch code. Boy scout rule applies. |

## The Non-Negotiable Checklist

Before you declare ANY documentation complete, verify ALL:

**For README:**
- [ ] Project title and description
- [ ] Installation instructions
- [ ] Usage instructions
- [ ] Configuration (if applicable)
- [ ] Available scripts
- [ ] Project structure

**For API Documentation:**
- [ ] Endpoint URL and method
- [ ] Description
- [ ] Request parameters/headers
- [ ] Response format (success and error)
- [ ] At least one example

**For Code Comments:**
- [ ] Complex algorithms explained
- [ ] Business logic documented
- [ ] "Why" documented, not just "what"

**Missing even ONE checkbox = documentation is NOT complete. Go back.**

## Real-World Pressure Scenarios

### "Self-Documenting Code" Scenario
**Situation:** Complex algorithm with clear variable names, tight deadline.

**Wrong response:** Skip documentation because code is readable.

**Right response:**
- Readable code shows WHAT, not WHY
- Complex algorithms need context: assumptions, trade-offs, edge cases
- 30 minutes of documentation saves hours of confusion
- Code review will go faster with documented intent

**Key insight:** "Self-documenting" is a myth for complex logic. Document the WHY.

### "We'll Document Later" Scenario
**Situation:** Team lead says ship now, document in next sprint.

**Wrong response:** Defer documentation indefinitely.

**Right response:**
- "Later" never comes - it's always "next sprint"
- Documentation has compound ROI - write it while context is fresh
- Push back diplomatically: "I can write minimal docs in 30 min now, full docs next sprint"
- If overruled: Document minimal critical info (setup, API contracts) immediately

**Key insight:** "Later" is a lie. Document alongside code.

### "Nobody Reads Docs" Scenario
**Situation:** Senior dev says nobody reads API docs, just use Swagger.

**Wrong response:** Accept Swagger-only documentation.

**Right response:**
- Past experience ≠ universal truth
- Developers DO read docs when they need help
- Swagger provides basics, not comprehensive examples
- ROI is long-term: docs help future developers (including future you)

**Key insight:** Document for the developer who WILL need this, not for current skeptics.

### "Just the README" Scenario
**Situation:** Manager says basic README for complex monorepo.

**Wrong response:** Accept minimal scope without advocating.

**Right response:**
- Advocate for completeness: "I recommend sections X, Y, Z for a monorepo this complex"
- If manager still wants basic: Comply, but document the decision and gaps
- Suggest phased approach: "Basic README now, architecture docs in next sprint"

**Key insight:** Professionalism means advocating for what's right, even if overruled.

### "Types Are Sufficient" Scenario
**Situation:** TypeScript library with well-defined types, time pressure.

**Wrong response:** Skip examples because types are clear.

**Right response:**
- Types show INTERFACE, not USAGE
- Examples demonstrate practical application
- Complex generics are hard to understand without examples
- At minimum: 1 example per public function

**Key insight:** Types are academic; examples are practical. Developers need both.

### Volatile API Scenario
**Situation:** API changes frequently, documentation becomes outdated quickly.

**Wrong response:** Skip documentation because it'll be outdated anyway.

**Right response:**
- Write comprehensive docs for current state
- Design for easy updates: modular structure, versioned sections
- Automate checks: docs-code synchronization tools
- Establish update process: Update docs with each PR that changes behavior
- Living documentation is maintainable documentation

**Key insight:** Documentation for volatile systems isn't futile - it's essential. Make it living, not static.

### Auto-Generated Documentation Scenario
**Situation:** Framework auto-generates comprehensive API docs from code.

**Wrong response:** Accept auto-generated docs as sufficient.

**Right response:**
- Auto-generated docs handle signatures and types well
- Manual docs provide: usage examples, common patterns, tutorials
- Developers need BOTH: what functions do (auto) AND how to use them (manual)
- Add manual layer on top of auto-generated foundation

**Key insight:** Auto-generated docs are a foundation, not a complete solution. Manual additions provide the practical layer.

### Multi-Audience Scenario
**Situation:** Documentation serves both technical and non-technical stakeholders.

**Wrong response:** Skip technical docs because audience is non-technical.

**Right response:**
- Create executive summary for business stakeholders (1-2 pages, no jargon)
- Create technical documentation for developers (comprehensive)
- Link between them: "For technical details, see [Technical Docs]"
- Serve both audiences with separate documents

**Key insight:** Don't compromise technical completeness for audience. Serve both with separate documents.

### Open-Source Documentation Scenario
**Situation:** Detailed docs might help competitors copy your approach.

**Wrong response:** Minimize documentation to protect competitive advantage.

**Right response:**
- Open-source philosophy means sharing knowledge
- Competitive advantage comes from execution, not hidden knowledge
- Better docs = more adoption = more contributors
- Hiding docs contradicts open-source principles and slows community growth

**Key insight:** Document comprehensively. Your advantage is speed and quality, not information asymmetry.

### Documentation Debt Scenario
**Situation:** Large codebase with 2 years of minimal documentation.

**Wrong response:** Accept debt or propose 6-month documentation project.

**Right response:**
- Document new code comprehensively (skill requirement)
- For existing code: Document as you touch it (boy scout rule)
- Prioritize: Document critical paths and complex logic first
- Create templates for quick documentation
- Establish team norm: Add docs when modifying code

**Key insight:** Documentation debt is addressed incrementally, not with big-bang projects. Every code change is an opportunity to improve documentation.

## Maintenance Guidelines

### Keep Documentation Updated
- Update docs when code changes
- Review docs before releases
- Remove outdated information
- Keep examples working

### Documentation Review Checklist
- [ ] All sections are complete
- [ ] Code examples are tested
- [ ] Links are working
- [ ] Spelling and grammar checked
- [ ] Formatting is consistent
- [ ] Screenshots are current (if any)

## Bottom Line

**Documentation isn't optional. It's professional.**

No matter the time pressure, "self-documenting" claims, authority suggestions, or scope limitations - you write documentation:

1. README for every project
2. API docs for every endpoint
3. Comments for complex logic
4. Examples for public APIs

**Skipping documentation = unprofessional. No exceptions.**

这个文档助手质量扎实，胜在内容全面细致。它不仅告诉你该写什么文档，还通过大量真实场景和反例来说明为什么要这样做，帮助克服“偷懒写文档”的心理。提供的模板和示例拿来就能用，上手很快。不足之处是内容偏向前端开发，后端或其他技术栈的开发者可能会觉得不太对口，另外缺少针对不同规模项目的差异化建议。总体来说瑕不掩瑜，是一份实用的文档编写指南。