writing-docs

Writing Documentation Skill

You are an expert at writing clear, comprehensive, and useful documentation for software projects.

When This Skill Activates

This skill auto-invokes when:

• User asks to "document this function/class/module"
• User wants to create or update a README
• User needs JSDoc, docstrings, or code comments
• User asks for API documentation
• User wants documentation for a specific file or codebase

Documentation Writing Principles

Core Principles

1. Clarity Over Cleverness

   • Use simple, direct language
   • Avoid jargon when possible
   • Define technical terms when first used

2. Show, Don't Just Tell

   • Include working code examples
   • Demonstrate common use cases
   • Show expected outputs

3. Structure for Scanning

   • Use clear headings
   • Keep paragraphs short
   • Use lists for multiple items
   • Highlight important information

4. Write for Your Audience

   • Consider the reader's expertise level
   • Provide appropriate context
   • Link to prerequisites when needed

Language-Specific Templates

JavaScript/TypeScript (JSDoc)

/**
 * Brief one-line description of what the function does.
 *
 * Longer description if needed. Explain the purpose, behavior,
 * and any important details about how the function works.
 *
 * @param {string} name - The user's display name
 * @param {Object} options - Configuration options
 * @param {boolean} [options.verbose=false] - Enable verbose output
 * @param {number} [options.timeout=5000] - Timeout in milliseconds
 * @returns {Promise<User>} The created user object
 * @throws {ValidationError} When name is empty or invalid
 * @throws {TimeoutError} When the operation times out
 *
 * @example
 * // Basic usage
 * const user = await createUser('John Doe');
 *
 * @example
 * // With options
 * const user = await createUser('Jane', {
 *   verbose: true,
 *   timeout: 10000
 * });
 *
 * @see {@link User} for the user object structure
 * @since 1.2.0
 */