C0ntr0lledcha0s Claude Code Plugin Automations 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
 */

Python (Google Style Docstrings)

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

// 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 Doe", nil)
//	if err != nil {
//	    log.Fatal(err)
//	}
//
// Errors:
//   - ErrEmptyName: returned when name is empty
//   - ErrInvalidName: returned when name contains invalid characters
func CreateUser(name string, opts *UserOptions) (*User, error) {

Rust

/// Creates a new user with the given name.
///
/// This function validates the name, initializes a User struct with default
/// values, and returns the new user. The user is not persisted to the
/// database until [`User::save`] is called.
///
/// # Arguments
///
/// * `name` - The user's display name. Must be non-empty.
/// * `options` - Optional configuration settings.
///
/// # Returns
///
/// Returns `Ok(User)` on success, or an error if validation fails.
///
/// # Errors
///
/// * [`UserError::EmptyName`] - If `name` is empty.
/// * [`UserError::InvalidName`] - If `name` contains invalid characters.
///
/// # Examples
///
/// Basic usage:
///
/// ```
/// let user = create_user("John Doe", None)?;
/// ```
///
/// With options:
///
/// ```
/// let opts = UserOptions { verbose: true, ..Default::default() };
/// let user = create_user("Jane", Some(opts))?;
/// ```
///
/// # Panics
///
/// This function does not panic under normal circumstances.

README Template

# Project Name

Brief description of what this project does and why it exists.

## Features

- Feature 1: Brief description
- Feature 2: Brief description
- Feature 3: Brief description

## Installation

### Prerequisites

- Requirement 1 (version X.X+)
- Requirement 2

### Install via [package manager]

\`\`\`bash
npm install project-name
# or
pip install project-name
\`\`\`

### Install from source

\`\`\`bash
git clone https://github.com/user/project-name
cd project-name
npm install
\`\`\`

## Quick Start

\`\`\`javascript
import { Project } from 'project-name';

const project = new Project();
project.doSomething();
\`\`\`

## Usage

### Basic Example

\`\`\`javascript
// Code example with comments
\`\`\`

### Advanced Usage

\`\`\`javascript
// More complex example
\`\`\`

## API Reference

### `functionName(param1, param2)`

Description of the function.

**Parameters:**
- `param1` (Type): Description
- `param2` (Type, optional): Description. Default: `value`

**Returns:** Type - Description

**Example:**
\`\`\`javascript
const result = functionName('value', { option: true });
\`\`\`

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `option1` | string | `"default"` | Description |
| `option2` | number | `10` | Description |

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing`)
5. Open a Pull Request

## License

[License Type] - see [LICENSE](LICENSE) for details.

Writing Guidelines

Function Documentation

Always Include:

1. Brief description (first line)
2. Parameter descriptions with types
3. Return value description
4. Possible errors/exceptions
5. At least one example

Include When Relevant:

• Side effects
• Performance considerations
• Thread safety notes
• Deprecation notices
• Links to related functions

Class Documentation

Always Include:

1. Class purpose and responsibility
2. Constructor documentation
3. Public method documentation
4. Important properties

Include When Relevant:

• Inheritance relationships
• Interface implementations
• State management notes
• Lifecycle information

Module/File Documentation

Always Include:

1. Module purpose
2. Main exports
3. Usage overview

Include When Relevant:

• Dependencies
• Configuration requirements
• Architecture notes

Common Patterns

Documenting Options Objects

/**
 * @typedef {Object} CreateUserOptions
 * @property {boolean} [verbose=false] - Enable verbose logging
 * @property {number} [timeout=5000] - Operation timeout in ms
 * @property {string} [role='user'] - Initial user role
 */

/**
 * Creates a user with the specified options.
 * @param {string} name - User name
 * @param {CreateUserOptions} [options] - Configuration options
 */

Documenting Callbacks

/**
 * @callback UserCallback
 * @param {Error|null} error - Error if operation failed
 * @param {User} user - The user object if successful
 */

/**
 * Fetches a user asynchronously.
 * @param {string} id - User ID
 * @param {UserCallback} callback - Called with result
 */

Documenting Generic Types

/**
 * A generic result wrapper.
 * @template T - The type of the success value
 * @template E - The type of the error value
 */
interface Result<T, E> {
  /** Whether the operation succeeded */
  success: boolean;
  /** The success value, if success is true */
  value?: T;
  /** The error value, if success is false */
  error?: E;
}

Quality Checklist

Before finalizing documentation, verify:

• First line is a clear, concise summary
• All parameters are documented with types
• Return value is documented
• Errors/exceptions are documented
• At least one working example is included
• Example code is tested and correct
• Language is clear and grammatically correct
• Formatting is consistent with codebase style
• Links to related documentation are included
• Edge cases and limitations are noted

Integration

This skill works with:

• analyzing-docs skill for identifying what needs documentation
• managing-docs skill for organizing documentation structure
• docs-analyzer agent for comprehensive documentation projects

Converted and distributed by TomeVault — claim your Tome and manage your conversions.