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