--- name: documentation-writing-24a94f2fe5f9 description: Technical documentation best practices and API documentation license: MIT compatibility: typedoc 0.25+, jsdoc 4+, markdown allowed-tools: read_file write_file apply_patch search_with_context --- # Documentation Writing ## Core Principles 1. **Audience-focused** - Know who you're writing for 2. **Task-oriented** - Help users accomplish goals 3. **Scannable** - Use headers, lists, and code blocks 4. **Accurate** - Keep in sync with code 5. **Complete** - Cover common use cases and edge cases ## README Structure ```markdown # Project Name Brief description (1-2 sentences). ## Features - Feature 1 - Feature 2 ## Installation ```bash npm install package-name ``` ## Quick Start ```typescript import { thing } from 'package-name'; // Minimal working example ``` ## Usage ### Basic Usage Detailed examples with explanations. ### Advanced Usage Complex scenarios and configuration. ## API Reference Link to detailed docs or inline reference. ## Contributing How to contribute to the project. ## License MIT ``` ## JSDoc/TSDoc Comments ### Functions ```typescript /** * Calculates the total price including tax. * * @param basePrice - The price before tax * @param taxRate - Tax rate as a decimal (e.g., 0.08 for 8%) * @returns The total price with tax applied * * @example * ```ts * const total = calculateTotal(100, 0.08); * // Returns: 108 * ``` * * @throws {RangeError} If taxRate is negative */ function calculateTotal(basePrice: number, taxRate: number): number { if (taxRate < 0) throw new RangeError('Tax rate cannot be negative'); return basePrice * (1 + taxRate); } ``` ### Classes ```typescript /** * Manages user authentication and session state. * * @remarks * This class handles OAuth2 authentication flows and maintains * session tokens in secure storage. * * @example * ```ts * const auth = new AuthManager({ clientId: 'xxx' }); * await auth.login(); * const user = auth.getCurrentUser(); * ``` */ class AuthManager { /** * Creates a new AuthManager instance. * @param config - Authentication configuration options */ constructor(config: AuthConfig) {} /** * Initiates the login flow. * @returns Promise that resolves when authentication completes */ async login(): Promise {} } ``` ### Interfaces ```typescript /** * Configuration options for the API client. */ interface ApiClientConfig { /** * Base URL for all API requests. * @example "https://api.example.com/v1" */ baseUrl: string; /** * Request timeout in milliseconds. * @default 30000 */ timeout?: number; /** * Custom headers to include in all requests. */ headers?: Record; } ``` ## API Documentation ### OpenAPI/Swagger ```yaml openapi: 3.0.3 info: title: User API version: 1.0.0 description: API for managing users paths: /users: get: summary: List all users description: Returns a paginated list of users parameters: - name: page in: query schema: type: integer default: 1 - name: limit in: query schema: type: integer default: 20 responses: '200': description: Successful response content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/User' meta: $ref: '#/components/schemas/Pagination' ``` ### Endpoint Documentation ```markdown ## Create User Creates a new user account. ### Request `POST /api/v1/users` #### Headers | Header | Required | Description | |--------|----------|-------------| | Authorization | Yes | Bearer token | | Content-Type | Yes | application/json | #### Body ```json { "email": "user@example.com", "name": "John Doe", "role": "user" } ``` | Field | Type | Required | Description | |-------|------|----------|-------------| | email | string | Yes | Valid email address | | name | string | Yes | 2-100 characters | | role | string | No | "user" or "admin" (default: "user") | ### Response #### Success (201 Created) ```json { "success": true, "data": { "id": "usr_abc123", "email": "user@example.com", "name": "John Doe", "createdAt": "2025-01-02T12:00:00Z" } } ``` #### Error (400 Bad Request) ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "email": "Invalid email format" } } } ``` ``` ## Code Examples ### Good Example ```typescript // ✅ Shows real use case with context import { createClient } from 'my-api'; const client = createClient({ apiKey: process.env.API_KEY, region: 'us-east-1', }); // Fetch user with error handling try { const user = await client.users.get('user_123'); console.log(`Found user: ${user.name}`); } catch (error) { if (error.code === 'NOT_FOUND') { console.log('User does not exist'); } else { throw error; // Re-throw unexpected errors } } ``` ### Bad Example ```typescript // ❌ Too abstract, no context const client = new Client(options); const result = client.doThing(data); ``` ## Changelog Format ```markdown # Changelog ## [1.2.0] - 2025-01-02 ### Added - New `exportToPDF()` method for reports (#123) - Support for custom themes ### Changed - Improved performance of data loading by 40% - Updated minimum Node.js version to 18 ### Fixed - Fixed memory leak in long-running processes (#456) - Corrected timezone handling for scheduled tasks ### Deprecated - `legacyExport()` - use `exportToPDF()` instead ### Security - Updated dependencies to patch CVE-2025-XXXX ``` ## Best Practices 1. **Write for scanning** - Use headers, bullets, tables 2. **Show, don't tell** - Include working code examples 3. **Keep examples minimal** - Show the concept, not everything 4. **Update with code** - Docs rot faster than code 5. **Test your examples** - Ensure they actually work 6. **Link liberally** - Connect related concepts 7. **Use consistent terminology** - Define terms once 8. **Include troubleshooting** - Common errors and solutions --- Source attribution: NeverSight Original project: https://github.com/NeverSight/skills_feed/blob/8db54595422f40924a0e2c3365b2f40e9aba0ad4/data/skills-md/autohandai/community-skills/documentation-writing/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: NeverSight Original project: https://github.com/NeverSight/skills_feed/blob/8db54595422f40924a0e2c3365b2f40e9aba0ad4/data/skills-md/autohandai/community-skills/documentation-writing/SKILL.md Attribution basis: Source repository record Fields of work: Content & Media, Product Management, Development & Engineering Roles: Technical Writer, Product Manager, Backend Developer Specialties: API Tools: Typedoc, Jsdoc Country applicability: Country not specified Classification basis: Source category, role and specialization labels Instruction SHA-256: 07bbf8a87ff8ba0fb623928d04487e1bce7cd0fb75ba7383415882e1b2b1bd4c