documentation-guidelines

Documentation Guidelines

Standardize documentation creation and update workflow to avoid unnecessary documentation generation.

Core Principles

1. Passive Documentation Creation

Core: Don't proactively create documentation unless there's clear need

Reasons:

• Avoid creating unmaintained documentation
• Documentation easily becomes outdated and out of sync
• Code itself should be self-documenting
• Time better spent on code quality

2. Code First

Priority:

1. Write clear, readable code
2. Add necessary code comments
3. Write type definitions and interface documentation
4. Consider external documentation last

When NOT to Create Documentation

❌ Don't create documentation for:

1. Non-critical tasks - Temporary code adjustments, small bug fixes
2. Exploratory work - Trying different approaches, prototyping
3. User didn't explicitly request - After completing features
4. Code is already clear - Clear naming, complete type definitions
5. Temporary code - Debug helper code, temporary scripts

When to Create Documentation

✅ Create documentation for:

1. User explicitly requests - "Help me write API usage documentation"
2. Critical tasks or important features - Core modules, complex architecture, critical configs, important APIs
3. Complex setup processes - Deployment workflows, environment config, third-party service integration
4. For other developers - Open source projects, internal shared libraries, CLI tools
5. Existing documentation needs update - Code changes affect existing documentation

Documentation Update Workflow

Strictly follow this order:

1. Complete code implementation
   ↓
2. Run code quality checks
   ├─ pnpm format
   ├─ pnpm lint
   ├─ pnpm typecheck
   └─ pnpm test
   ↓
3. All checks pass
   ↓
4. Update relevant documentation
   ↓
5. Commit code and documentation

Why this order?

• Avoid duplicate work - code may change during checks
• Ensure accuracy - documentation based on final, verified code
• Improve efficiency - focus on one task at a time
• Reduce omissions - documentation update not forgotten after code passes checks