writing-docs

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: writing-docs
description: >
  Expert at writing high-quality documentation for code, APIs, and projects. Auto-invokes when
  generating docstrings, creating README files, writing API documentation, adding code comments,
  or producing any technical documentation. Provides language-specific templates and best practices
  for effective documentation writing.
allowed-tools: Read, Write, Edit, Glob, Grep
---

# 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)

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

### Python (Google Style Docstrings)

```python
def create_user(name: str, **options) -> User:
    """Create a new user with the given name.

    Longer description if needed. Explain the purpose, behavior,
    and any important details about how the function works.

    Args:
        name: The user's display name. Must be non-empty.
        **options: Optional keyword arguments.
            verbose (bool): Enable verbose output. Defaults to False.
            timeout (int): Timeout in milliseconds. Defaults to 5000.

    Returns:
        User: The created user object with populated fields.

    Raises:
        ValidationError: When name is empty or invalid.
        TimeoutError: When the operation times out.

    Example:
        Basic usage::

            user = create_user('John Doe')

        With options::

            user = create_user('Jane', verbose=True, timeout=10000)

    Note:
        The user is not persisted until `user.save()` is called.

    See Also:
        User: The user object class.
    """
```

### Go

```go
// CreateUser creates a new user with the given name.
//
// CreateUser validates the name, initializes a User struct with default
// values, and returns a pointer to the new user. The user is not persisted
// to the database until Save() is called.
//
// Parameters:
//   - name: The user's display name. Must be non-empty string.
//   - opts: Optional configuration. See UserOptions for available options.
//
// Returns the created User pointer and any error encountered.
//
// Example:
//
//	user, err := CreateUser("John