documentation-implementation（文档实现）

Documentation Implementation Skill

Domain-specific guidance for creating clear, comprehensive technical documentation.

When To Use This Skill

Load this Skill when task has tags:

• documentation, docs, user-docs, api-docs
• guide, readme, tutorial, reference

Validation Commands

Check Documentation

# Markdown linting
npx markdownlint **/*.md

# Spell check
npx cspell "**/*.md"

# Link checking
npx markdown-link-check docs/**/*.md

# Build documentation site (if applicable)
npm run docs:build
mkdocs build

Preview Documentation

# Live preview
npm run docs:serve
mkdocs serve

# Static site preview
python -m http.server 8000 -d docs/

Success Criteria (Before Completing Task)

✅ Documentation is accurate (reflects actual behavior) ✅ Documentation is complete (all required sections present) ✅ Examples work (code examples run without errors) ✅ Links are valid (no broken links) ✅ Spelling and grammar correct ✅ Follows project style guide

Common Documentation Tasks

API Documentation

• Endpoint descriptions (path, method)
• Request parameters (required, optional, types)
• Response schemas (success, error)
• Status codes (200, 400, 401, 404, 500)
• Example requests/responses
• Authentication requirements

User Guides

• Step-by-step instructions
• Screenshots or diagrams
• Prerequisites
• Troubleshooting section
• FAQs

README Files

• Project overview
• Installation instructions
• Quick start guide
• Configuration options
• Contributing guidelines

Code Documentation

• Function/method descriptions
• Parameter documentation
• Return value documentation
• Usage examples
• Edge cases and gotchas

Documentation Patterns

API Endpoint Documentation

## POST /api/users

Creates a new user account.

**Authentication:** Required (Bearer token)

**Request Body:**

{ "email": " [email protected] ", // Required, must be valid email "password": "secure123", // Required, min 8 characters "name": "John Doe" // Required }

**Success Response (201 Created):**

{ "id": "550e8400-e29b-41d4-a716-446655440000", "email": " [email protected] ", "name": "John Doe", "createdAt": "2024-01-15T10:30:00Z" }

**Error Responses:**

- **400 Bad Request** - Invalid input

{ "error": "Invalid email format", "code": "VALIDATION_ERROR" }

- **409 Conflict** - Email already exists

{ "error": "Email already registered", "code": "DUPLICATE_EMAIL" }

**Example Request:**

curl -X POST https://api.example.com/api/users \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "email": " [email protected] ", "password": "secure123", "name": "John Doe" }'

User Guide Pattern

# Setting Up User Authentication

This guide walks you through enabling user authentication in your application.

## Prerequisites

- Node.js 18+ installed
- Database configured
- Admin access to the application

## Step 1: Install Required Packages

npm install bcrypt jsonwebtoken express-session

## Step 2: Configure Environment Variables

Create a `.env` file in your project root:

JWT_SECRET=your-secret-key-here SESSION_TIMEOUT=3600

## Step 3: Enable Authentication

Edit `config/app.js` and add:

const authMiddleware = require('./middleware/auth'); app.use(authMiddleware);

## Step 4: Test Authentication

1. Start your application: `npm start`
2. Navigate to http://localhost:3000/login
3. Use test credentials:
   - Email:  [email protected] 
   - Password: test123
4. You should be redirected to the dashboard

## Troubleshooting

**Problem:** Login fails with "Invalid credentials"
**Solution:** Check that you've run database migrations: `npm run migrate`

**Problem:** Session expires immediately
**Solution:** Verify JWT_SECRET is set in `.env` file

Code Documentation Pattern

/**
 * Creates a new user account with the provided information.
 *
 * This function validates the user data, hashes the password using bcrypt,
 * and persists the user to the database. Email uniqueness is enforced at
 * the database level.
 *
 * @param email User's email address (must be valid format and unique)
 * @param password Plain text password (min 8 characters, will be hashed)
 * @param name User's full name
 * @return Created user with generated ID and timestamps
 * @throws ValidationException if email format is invalid or password too short
 * @throws DuplicateEmailException if email already registered
 * @throws DatabaseException if database operation fails
 *
 * @example
 * ```kotlin
 * val user = userService.createUser(
 *     email = " [email protected] ",
 *     password = "secure123",
 *     name = "John Doe"
 * )
 * println(user.id)  // UUID generated by database
 * ```
 *
 * @see User
 * @see validateEmail
 * @see hashPassword
 */
fun createUser(email: String, password: String, name: String): User {
    // Implementation
}

Common Blocker Scenarios

Blocker 1: Implementation Incomplete

Issue: Cannot document features that don't exist yet

What to try:

• Check if implementation task is truly complete
• Test the feature manually
• Check API responses match requirements

If blocked: Report to orchestrator - implementation incomplete or requirements unclear

Blocker 2: API Behavior Unclear

Issue: Don't know what endpoint does, what parameters mean, or what responses look like

What to try:

• Test API endpoints manually (Postman, curl)
• Read implementation code
• Check for existing API specs (OpenAPI, GraphQL schema)
• Check task requirements

If blocked: Report to orchestrator - need clarification on API behavior

Blocker 3: Missing Design Assets

Issue: User guide needs screenshots but UI not implemented or accessible

What to try:

• Use placeholder images with captions
• Describe steps verbally without screenshots
• Check if mockups/designs available

If blocked: Report to orchestrator - need access to UI or design assets

Blocker 4: Contradictory Information

Issue: Code does X, requirements say Y, existing docs say Z

What to try:

• Test actual behavior
• Document what code actually does
• Note discrepancy in comments

If blocked: Report to orchestrator - need authoritative answer on correct behavior

Blocker 5: Technical Details Missing

Issue: Don't know how something works internally to document it

What to try:

• Read implementation code
• Ask implementation engineer (check task history)
• Document what's observable from outside

If blocked: Report to orchestrator - need technical details from implementer

Blocker Report Format

⚠️ BLOCKED - Requires Senior Engineer

Issue: [Specific problem - implementation incomplete, unclear behavior, etc.]

Attempted Research:
- [What sources you checked]
- [What you tried to find out]
- [Why it didn't work]

Blocked By: [Task ID / incomplete implementation / unclear requirements]

Partial Progress: [What documentation you DID complete]

Requires: [What needs to happen to unblock documentation]

Documentation Quality Checklist

Clarity

✅ Uses simple, clear language ✅ Defines technical terms on first use ✅ Short sentences (< 25 words) ✅ Active voice ("Click the button" not "The button should be clicked") ✅ Consistent terminology (don't switch between "user" and "account")

Completeness

✅ All required sections present ✅ All parameters documented ✅ All status codes explained ✅ Edge cases covered ✅ Examples provided ✅ Troubleshooting section included

Accuracy

✅ Code examples run without errors ✅ Screenshots match current UI ✅ API responses match actual responses ✅ Links work (no 404s) ✅ Version numbers correct

Formatting

✅ Consistent heading levels ✅ Code blocks have language specified ✅ Lists use consistent bullet style ✅ Tables formatted correctly ✅ Proper markdown syntax

Writing Style Guidelines

Use Active Voice

❌ Passive: "The user object is returned by the API" ✅ Active: "The API returns the user object"

Be Specific

❌ Vague: "Call the endpoint with the data" ✅ Specific: "Send a POST request to /api/users with email, password, and name"

Show, Don't Just Tell

❌ Abstract: "Configure the authentication settings" ✅ Concrete:

Edit config/auth.js and set:

module.exports = { jwtSecret: 'your-secret-here', tokenExpiry: '24h' };

Include Examples

Every documented feature should have:

• Code example showing usage
• Expected output
• Common use cases

Anticipate Questions

After each instruction, ask:

• What could go wrong here?
• What might be unclear?
• What would I wonder about?

Add troubleshooting for those questions.

Common Patterns to Follow

1. Start with overview - what it is, why it matters
2. Prerequisites first - what user needs before starting
3. Step-by-step instructions - numbered, one action per step
4. Examples that work - test all code examples
5. Troubleshooting section - common problems and solutions
6. Clear formatting - headings, code blocks, lists
7. Links to related docs - help users find more information

What NOT to Do

❌ Don't use jargon without explaining it ❌ Don't assume prior knowledge ❌ Don't skip error cases ❌ Don't provide untested code examples ❌ Don't use vague terms ("simply", "just", "obviously") ❌ Don't forget to update docs when code changes ❌ Don't document implementation details users don't need

Focus Areas

When reading task sections, prioritize:

• requirements - What needs documenting
• context - Purpose and audience
• documentation - Existing docs to update
• implementation - How it actually works

Remember

• Accuracy is critical - test everything you document
• Clarity over cleverness - simple language wins
• Examples are essential - every feature needs working examples
• Update, don't duplicate - check if docs already exist
• Test your instructions - follow them yourself
• Report blockers promptly - missing information, incomplete features
• Users read docs when stuck - be helpful and thorough

Additional Resources

For deeper patterns and examples, see:

• PATTERNS.md - Advanced documentation patterns, style guides (load if needed)
• BLOCKERS.md - Detailed documentation-specific blockers (load if stuck)
• examples.md - Complete documentation examples (load if uncertain)