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

Clarity Over Cleverness

• Use simple, direct language

• Avoid jargon when possible

• Define technical terms when first used

Show, Don't Just Tell

• Include working code examples

• Demonstrate common use cases

• Show expected outputs

Structure for Scanning

• Use clear headings

• Keep paragraphs short

• Use lists for multiple items

• Highlight important information

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

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 for details.

Writing Guidelines

Function Documentation

Always Include:

• Brief description (first line)

• Parameter descriptions with types

• Return value description

• Possible errors/exceptions

• At least one example

Include When Relevant:

• Side effects

• Performance considerations

• Thread safety notes

• Deprecation notices

• Links to related functions

Class Documentation

Always Include:

• Class purpose and responsibility

• Constructor documentation

• Public method documentation

• Important properties

Include When Relevant:

• Inheritance relationships

• Interface implementations

• State management notes

• Lifecycle information

Module/File Documentation

Always Include:

• Module purpose

• Main exports

• 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