文件助手
📖 技能介紹
name: 文件助手 description: 在建立任何文件、README檔案、API文件、程式碼註釋或技術指南時使用——防止遺漏文件，確保全面覆蓋，並強制要求在編寫程式碼的同時編寫文件，無論時間壓力、“自文件化”宣告或範圍限制如何
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
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:
| Column 1 | Column 2 |
|---|---|
| Data 1 | Data 2 |
- 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
```markdown
# 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
| Variable | Description | Default |
|---|---|---|
| VITE_API_URL | API base URL | - |
Scripts
| Command | Description |
|---|---|
| pnpm dev | Start development server |
| pnpm build | Build for production |
| pnpm test | Run tests |
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"
小蔥技能站7w4.net，專業的AI技能分享平臺。
- ❌ "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:
- README for every project
- API docs for every endpoint
- Comments for complex logic
- Examples for public APIs
Skipping documentation = unprofessional. No exceptions.
🤖 AI 評測
這個文件助手質量紮實，勝在內容全面細緻。它不僅告訴你該寫什麼文件，還通過大量真實場景和反例來說明為什麼要這樣做，幫助克服“偷懶寫文件”的心理。提供的模板和示例拿來就能用，上手很快。不足之處是內容偏向前端開發，後端或其他技術棧的開發者可能會覺得不太對口，另外缺少針對不同規模專案的差異化建議。總體來說瑕不掩瑜，是一份實用的文件編寫指南。
