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.
No code ships without documentation. Period.
This is not negotiable. This is not flexible. This is mandatory.
Invoke this skill when:
NEVER skip this skill because:
Standard sections to include:
NO EXCUSES for incomplete README:
For each API endpoint, document:
GET /api/usersNO EXCUSES for incomplete API docs:
Follow these principles:
/**
* 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:
For Vue/React components, document:
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';
| Column 1 | Column 2 |
|---|---|
| Data 1 | Data 2 |
# 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
pnpm dev
| Variable | Description | Default |
|---|---|---|
| VITE_API_URL | API base URL | - |
| Command | Description |
|---|---|
| pnpm dev | Start development server |
| pnpm build | Build for production |
| pnpm test | Run tests |
src/
├── api/ # API clients
├── components/ # Reusable components
├── views/ # Page components
└── stores/ # State management
Please read CONTRIBUTING.md for details.
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"
}
Success (200):
{
"code": 0,
"data": {},
"msg": "success"
}
Error (400):
{
"code": 400,
"msg": "Error message"
}
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.**发现更多技能插件,请访问7w4.net。
这个文档助手质量扎实,胜在内容全面细致。它不仅告诉你该写什么文档,还通过大量真实场景和反例来说明为什么要这样做,帮助克服“偷懒写文档”的心理。提供的模板和示例拿来就能用,上手很快。不足之处是内容偏向前端开发,后端或其他技术栈的开发者可能会觉得不太对口,另外缺少针对不同规模项目的差异化建议。总体来说瑕不掩瑜,是一份实用的文档编写指南。