document-writing-skills

# Document Writing Skills **Purpose**: This skill provides comprehensive document writing patterns, templates, and best practices that agents can apply when generating professional documentation, reports, contracts, guides, and technical writing across various domains. ## When to Use Document Writing Skills Use this skill when: - Creating API documentation (REST/GraphQL/RPC) - Writing technical documentation or user guides - Generating research reports or incident reports - Drafting architecture decision records (ADRs) - Creating changelogs and release notes - Writing legal memoranda or contracts - Producing test reports or security assessments - Authoring product requirement documents (PRDs) ## Core Writing Principles ### 1. Clarity and Conciseness **Guidelines**: - Use active voice: "The system processes requests" (not "Requests are processed by the system") - Use present tense: "The function returns" (not "The function will return") - Be specific: "Response time: 200ms" (not "Response time is fast") - Avoid jargon unless domain-appropriate - Use short sentences (15-20 words maximum) - Break complex ideas into numbered steps **Example - Before and After**: ``` ❌ Before: "It should be noted that the API endpoint might be utilized for the purpose of retrieving user data." ✅ After: "Use this endpoint to retrieve user data." ``` ### 2. Progressive Disclosure Structure Organize documents from high-level to detailed: 1. **Summary/Overview** - What and why (2-3 sentences) 2. **Key Concepts** - Essential understanding 3. **Details** - Deep-dive information 4. **Reference** - Complete specifications **Template**: ```markdown # Document Title ## Summary [2-3 sentences: What this is and why it matters] ## Quick Start [Minimal steps to get started] ## Concepts [Essential understanding] ## Detailed Guide [In-depth information] ## Reference [Complete specifications, API details, etc.] ``` ### 3. Consistency Standards **Maintain consistency in**: - Terminology (create glossary for domain terms) - Code formatting (use syntax highlighting) - Section structure (follow templates) - Date formats (ISO 8601: YYYY-MM-DD) - Version numbers (Semantic Versioning: MAJOR.MINOR.PATCH) --- ## Document Type Templates ### API Documentation **Structure**: ```markdown # API Endpoint: [Method] /path/to/endpoint ## Overview [Brief description of what this endpoint does] ## Authentication [Required authentication method] ## Request **Method**: [GET/POST/PUT/DELETE] **URL**: `/api/v1/endpoint` **Headers**: | Header | Value | Required | |--------|-------|----------| | Authorization | Bearer {token} | Yes | | Content-Type | application/json | Yes | **Parameters**: | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | user_id | integer | Yes | Unique user identifier | | limit | integer | No | Max results (default: 10) | **Request Body** (JSON): ```json { "field1": "value", "field2": 123 } ``` ## Response **Success Response** (200 OK): ```json { "status": "success", "data": { "id": 12345, "name": "Example" } } ``` **Error Responses**: | Status Code | Description | Response Body | |-------------|-------------|---------------| | 400 | Bad Request | `{"error": "Invalid parameters"}` | | 401 | Unauthorized | `{"error": "Authentication required"}` | | 404 | Not Found | `{"error": "Resource not found"}` | | 500 | Server Error | `{"error": "Internal server error"}` | ## Example Usage **cURL**: ```bash curl -X POST https://api.example.com/v1/endpoint \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"field1": "value"}' ``` **Python**: ```python import requests response = requests.post( "https://api.example.com/v1/endpoint", headers={"Authorization": "Bearer YOUR_TOKEN"}, json={"field1": "value"} ) ``` ## Rate Limiting [Rate limit details if applicable] ## Notes [Additional considerations, edge cases, deprecation warnings] ``` ### Technical Report **Structure**: ```markdown # [Report Title] **Author**: [Name/Role] **Date**: [YYYY-MM-DD] **Version**: [X.Y] **Status**: [Draft/Final/Approved] ## Executive Summary [2-3 paragraphs: Key findings, recommendations, impact] ## Background [Context: Why this report exists, what problem it addresses] ## Methodology [How the analysis was conducted, tools used, data sources] ## Findings ### Finding 1: [Title] **Impact**: [High/Medium/Low] **Evidence**: [Data, observations, metrics] **Analysis**: [What this means] ### Finding 2: [Title] [Same structure...] ## Recommendations ### Recommendation 1: [Action] **Priority**: [High/Medium/Low] **Effort**: [High/Medium/Low] **Timeline**: [Timeframe] **Rationale**: [Why this recommendation] ## Conclusion [Summary of key points and next steps] ## Appendix [Supporting data, detailed tables, raw results] ``` ### Architecture Decision Record (ADR) **Structure**: ```markdown # ADR-[Number]: [Title] **Status**: [Proposed/Accepted/Deprecated/Superseded] **Date**: [YYYY-MM-DD] **Deciders**: [Names/Roles] ## Context [What is the issue we're addressing?] ## Decision [What decision have we made?] ## Rationale [Why did we make this decision?] ### Options Considered #### Option 1: [Name] **Pros**: - [Advantage 1] - [Advantage 2] **Cons**: - [Disadvantage 1] - [Disadvantage 2] #### Option 2: [Name] [Same structure...] ### Decision Criteria - [Criterion 1: Performance] - [Criterion 2: Maintainability] - [Criterion 3: Cost] ## Consequences ### Positive - [Benefit 1] - [Benefit 2] ### Negative - [Trade-off 1] - [Trade-off 2] ### Neutral - [Impact 1] ## Implementation Notes [Guidance for implementing this decision] ## Related Decisions - [ADR-XXX: Related decision] ## References - [Documentation links, research papers, discussions] ``` ### User Guide **Structure**: ```markdown # [Product/Feature] User Guide ## Overview [What this is and what it helps users accomplish] ## Getting Started ### Prerequisites - [Requirement 1] - [Requirement 2] ### Installation 1. [Step 1 with validation] ```bash command-to-run ``` **Expected output**: [What success looks like] 2. [Step 2] [Validation checkpoint] ## Tutorials ### Tutorial 1: [Basic Task] **Goal**: [What you'll accomplish] **Time**: [Estimated duration] **Steps**: 1. [Action] - **Why**: [Rationale] - **Validation**: [How to verify success] 2. [Next action] [Same structure...] **Result**: [What you've achieved] ### Tutorial 2: [Advanced Task] [Same structure...] ## Reference ### Feature 1 **Description**: [What it does] **Usage**: [How to use it] **Parameters**: [Options available] **Examples**: [Common use cases] ## Troubleshooting ### Problem: [Common issue] **Symptoms**: [How to identify this problem] **Cause**: [Why this happens] **Solution**: [Step-by-step fix] ### Problem: [Another issue] [Same structure...] ## FAQ **Q: [Common question]** A: [Clear answer] ## Additional Resources - [Link to API docs] - [Link to community forum] ``` ### Changelog **Format**: Keep a Changelog (https://keepachangelog.com/en/1.0.0/) **Structure**: ```markdown # Changelog All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] ### Added - [New feature description] ### Changed - [Change to existing functionality] ### Deprecated - [Soon-to-be removed feature] ### Removed - [Removed feature] ### Fixed - [Bug fix] ### Security - [Vulnerability fix] ## [1.2.0] - 2025-11-08 ### Added - User authentication with JWT tokens - Password reset functionality - Email verification ### Changed - Improved API response times by 40% - Updated database schema for better performance ### Fixed - Issue #123: Login timeout on slow connections - Memory leak in background worker ## [1.1.0] - 2025-10-15 [Previous version changes...] ## [1.0.0] - 2025-09-01 ### Added - Initial release - User registration and login - Basic profile management [Unreleased]: https://github.com/org/repo/compare/v1.2.0...HEAD [1.2.0]: https://github.com/org/repo/compare/v1.1.0...v1.2.0 [1.1.0]: https://github.com/org/repo/compare/v1.0.0...v1.1.0 [1.0.0]: https://github.com/org/repo/releases/tag/v1.0.0 ``` **Breaking Changes Callout**: ```markdown ## [2.0.0] - 2025-11-08 ### ⚠️ BREAKING CHANGES - **Authentication**: Changed from session-based to JWT tokens - **Migration**: See [Migration Guide](./MIGRATION.md) - **Impact**: All clients must update authentication flow - **API Endpoints**: Removed deprecated `/v1/users` endpoint - **Replacement**: Use `/v2/users` instead ``` --- ## Visual Elements ### Code Examples **Always include**: - Syntax highlighting (specify language) - Complete working examples (not fragments) - Expected output - Error handling **Template**: ````markdown ```python # Complete example with imports import requests def get_user(user_id): """Retrieve user by ID.""" try: