developer-ai 1.0.0

package/skills/documentation/SKILL.md

@@ -0,0 +1,496 @@
+---
+name: documentation
+description: Guide for writing effective technical documentation. Use when creating README files, API docs, code comments, architecture docs, or onboarding guides. Covers documentation structure, writing style, and best practices for different doc types.
+---
+
+# Documentation Skill
+
+This skill provides guidance for creating clear, useful, and maintainable technical documentation.
+
+## Overview
+
+Good documentation is essential for project success. It helps users understand your code, enables team collaboration, and reduces support burden.
+
+## README Structure
+
+### Essential Sections
+
+```markdown
+# Project Name
+
+Brief one-line description of what the project does.
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm start
+\`\`\`
+
+## Installation
+
+Detailed installation instructions...
+
+## Usage
+
+Basic usage examples...
+
+## API Reference
+
+Link to API docs or brief reference...
+
+## Configuration
+
+Environment variables and config options...
+
+## Contributing
+
+How to contribute to the project...
+
+## License
+
+MIT License
+```
+
+### Good README Example
+
+```markdown
+# TaskFlow
+
+A lightweight task management CLI for developers who hate context switching.
+
+## Features
+
+- 🚀 Fast - Start tracking in < 1 second
+- 📝 Simple - No complex setup required
+- 🔄 Syncs - Works with GitHub Issues
+- 💻 CLI-first - Designed for terminal lovers
+
+## Quick Start
+
+\`\`\`bash
+# Install globally
+npm install -g taskflow
+
+# Initialize in your project
+taskflow init
+
+# Add your first task
+taskflow add "Fix login bug" --priority high
+\`\`\`
+
+## Installation
+
+### Prerequisites
+- Node.js 18+
+- npm or yarn
+
+### Install
+\`\`\`bash
+npm install -g taskflow
+\`\`\`
+
+## Usage
+
+### Create a Task
+\`\`\`bash
+taskflow add "Task description" [options]
+
+Options:
+  --priority, -p   Set priority (low, medium, high)
+  --due, -d        Set due date (YYYY-MM-DD)
+  --tag, -t        Add tags (comma-separated)
+\`\`\`
+
+### List Tasks
+\`\`\`bash
+taskflow list              # All tasks
+taskflow list --priority high
+taskflow list --tag bug
+\`\`\`
+
+### Complete a Task
+\`\`\`bash
+taskflow done <task-id>
+\`\`\`
+
+## Configuration
+
+Create `.taskflowrc` in your project root:
+
+\`\`\`json
+{
+  "defaultPriority": "medium",
+  "syncWithGitHub": true,
+  "githubRepo": "username/repo"
+}
+\`\`\`
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| TASKFLOW_HOME | Config directory | ~/.taskflow |
+| GITHUB_TOKEN | GitHub API token | - |
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+## License
+
+MIT © Your Name
+```
+
+## Code Comments
+
+### When to Comment
+
+**Comment WHY, not WHAT**
+```javascript
+// BAD - describes what code does
+// Loop through users
+for (const user of users) {
+  
+}
+
+// GOOD - explains why
+// Process users in batches to avoid memory issues
+// with large datasets (>10k users)
+for (const user of users) {
+  
+}
+```
+
+**Comment Complex Logic**
+```javascript
+// Calculate discount based on loyalty tier and purchase history
+// Tier 1: 5% base + 1% per year (max 10%)
+// Tier 2: 10% base + 1% per year (max 20%)
+// Tier 3: 15% base + 2% per year (max 30%)
+function calculateDiscount(customer) {
+  const baseDiscount = [5, 10, 15][customer.tier - 1];
+  const yearlyBonus = customer.tier === 3 ? 2 : 1;
+  const maxDiscount = [10, 20, 30][customer.tier - 1];
+  
+  return Math.min(
+    baseDiscount + (customer.yearsActive * yearlyBonus),
+    maxDiscount
+  );
+}
+```
+
+**Comment Non-Obvious Decisions**
+```javascript
+// Using Map instead of Object here because we need
+// to preserve insertion order for the UI display
+const orderedItems = new Map();
+```
+
+### JSDoc Comments
+
+```javascript
+/**
+ * Calculates the total price including tax and discounts.
+ * 
+ * @param {Object} order - The order object
+ * @param {number} order.subtotal - Order subtotal before tax
+ * @param {number} order.taxRate - Tax rate as decimal (e.g., 0.08)
+ * @param {number} [order.discount=0] - Discount amount to apply
+ * @returns {number} The final total price
+ * @throws {Error} If subtotal is negative
+ * 
+ * @example
+ * calculateTotal({ subtotal: 100, taxRate: 0.08, discount: 10 })
+ * // Returns: 98.00
+ */
+function calculateTotal({ subtotal, taxRate, discount = 0 }) {
+  if (subtotal < 0) {
+    throw new Error('Subtotal cannot be negative');
+  }
+  
+  const taxAmount = subtotal * taxRate;
+  return subtotal + taxAmount - discount;
+}
+```
+
+### TypeScript Documentation
+
+```typescript
+/**
+ * User account information.
+ */
+interface User {
+  /** Unique identifier */
+  id: string;
+  
+  /** User's display name */
+  name: string;
+  
+  /** Email address (must be verified) */
+  email: string;
+  
+  /** Account creation timestamp */
+  createdAt: Date;
+  
+  /** 
+   * User's role in the system.
+   * @default 'user'
+   */
+  role: 'admin' | 'moderator' | 'user';
+}
+```
+
+## API Documentation
+
+### Endpoint Documentation
+
+```markdown
+## Create User
+
+Creates a new user account.
+
+### Request
+
+`POST /api/v1/users`
+
+#### Headers
+
+| Name | Required | Description |
+|------|----------|-------------|
+| Authorization | Yes | Bearer token |
+| Content-Type | Yes | Must be `application/json` |
+
+#### Body
+
+\`\`\`json
+{
+  "name": "John Doe",
+  "email": "john@example.com",
+  "password": "securepassword123"
+}
+\`\`\`
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| name | string | Yes | User's full name (2-100 chars) |
+| email | string | Yes | Valid email address |
+| password | string | Yes | Min 8 chars, 1 number, 1 special |
+
+### Response
+
+#### Success (201 Created)
+
+\`\`\`json
+{
+  "id": "usr_abc123",
+  "name": "John Doe",
+  "email": "john@example.com",
+  "createdAt": "2024-01-15T10:30:00Z"
+}
+\`\`\`
+
+#### Errors
+
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | INVALID_REQUEST | Missing or invalid fields |
+| 409 | EMAIL_EXISTS | Email already registered |
+| 422 | VALIDATION_ERROR | Validation failed |
+
+### Example
+
+\`\`\`bash
+curl -X POST https://api.example.com/v1/users \
+  -H "Authorization: Bearer your-token" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "John Doe", "email": "john@example.com", "password": "pass123!"}'
+\`\`\`
+```
+
+## Architecture Documentation
+
+### Architecture Decision Records (ADR)
+
+```markdown
+# ADR 001: Use PostgreSQL for Primary Database
+
+## Status
+Accepted
+
+## Context
+We need to choose a primary database for the application.
+Requirements:
+- ACID compliance for financial transactions
+- Support for complex queries
+- Scalability to 10M+ records
+- Strong ecosystem and tooling
+
+## Decision
+We will use PostgreSQL as our primary database.
+
+## Consequences
+
+### Positive
+- Proven reliability for financial applications
+- Excellent query performance with proper indexing
+- Rich feature set (JSON support, full-text search)
+- Strong community and documentation
+
+### Negative
+- Requires more operational expertise than managed solutions
+- Schema migrations need careful planning
+- May need read replicas for high read workloads
+
+## Alternatives Considered
+
+### MySQL
+- Rejected: Less robust for complex transactions
+- Would work but PostgreSQL has better feature set
+
+### MongoDB
+- Rejected: Need strong consistency for financial data
+- Document model doesn't fit our relational data well
+```
+
+### Component Documentation
+
+```markdown
+# Authentication Service
+
+## Overview
+
+Handles user authentication and authorization across the platform.
+
+## Architecture
+
+\`\`\`
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│   Client    │────▶│  Auth API    │────▶│  Database   │
+└─────────────┘     └──────────────┘     └─────────────┘
+                           │
+                           ▼
+                    ┌──────────────┐
+                    │    Redis     │
+                    │  (Sessions)  │
+                    └──────────────┘
+\`\`\`
+
+## Components
+
+### AuthController
+Handles HTTP requests for login, logout, and token refresh.
+
+### TokenService
+Manages JWT creation, validation, and refresh.
+
+### UserRepository
+Database operations for user authentication.
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | /auth/login | Authenticate user |
+| POST | /auth/logout | Invalidate session |
+| POST | /auth/refresh | Refresh access token |
+
+## Configuration
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| JWT_SECRET | Secret for signing tokens | Yes |
+| JWT_EXPIRY | Token expiration time | Yes |
+| REDIS_URL | Redis connection URL | Yes |
+
+## Security Considerations
+
+- Tokens expire after 15 minutes
+- Refresh tokens stored in httpOnly cookies
+- Failed login attempts rate-limited
+- Sessions invalidated on password change
+```
+
+## Writing Style Guide
+
+### Be Concise
+```markdown
+# BAD
+In order to facilitate the installation process, you will need
+to execute the following command in your terminal application.
+
+# GOOD
+Install with:
+\`\`\`bash
+npm install package-name
+\`\`\`
+```
+
+### Use Active Voice
+```markdown
+# BAD
+The configuration file should be modified by the user.
+
+# GOOD
+Modify the configuration file:
+```
+
+### Be Specific
+```markdown
+# BAD
+This may cause issues.
+
+# GOOD
+This causes a memory leak when processing more than 1000 items.
+```
+
+### Use Examples
+```markdown
+# BAD
+Pass the options object to configure.
+
+# GOOD
+Configure with options:
+\`\`\`javascript
+configure({
+  timeout: 5000,
+  retries: 3,
+  debug: true
+});
+\`\`\`
+```
+
+## Documentation Checklist
+
+### README
+- [ ] Clear project description
+- [ ] Quick start guide
+- [ ] Installation instructions
+- [ ] Basic usage examples
+- [ ] Configuration options
+- [ ] Contributing guidelines
+
+### Code Comments
+- [ ] Complex logic explained
+- [ ] Why, not what
+- [ ] Public APIs documented
+- [ ] Examples included
+
+### API Docs
+- [ ] All endpoints documented
+- [ ] Request/response formats
+- [ ] Error codes explained
+- [ ] Authentication documented
+- [ ] Examples provided
+
+### Architecture
+- [ ] System overview
+- [ ] Component relationships
+- [ ] Key decisions documented
+- [ ] Security considerations