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:**
```json
{
  "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 json { "error": "Invalid email format", "code": "VALIDATION_ERROR" }

• 409 Conflict - Email already exists json { "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

```markdown
# 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

```bash
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

```kotlin
/**
 * 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:
```javascript
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)