Documentation Generation

When to Use

• After implementing new features with public interfaces
• When making breaking changes
• When adding complex algorithms or business logic
• Before shipping a phase or milestone
• When documentation is flagged as incomplete
• When conversation mentions: document, README, API docs, changelog

Natural Language Triggers

• "document this", "write docs", "update README", "API docs", "needs documentation"

Generate accurate, useful documentation that serves its audience. API docs for developers, guides for users, architecture docs for maintainers.

The documenter agent references this skill for systematic documentation generation.

Documentation Types

1. Code Documentation (Inline)

Document non-obvious code for developers reading the implementation.

What to document:

• Complex algorithms and business logic
• Non-obvious design decisions
• Workarounds and edge cases
• Performance considerations

What NOT to document: Anything a competent developer can understand by reading the code itself.

Format: Docstrings with parameters, returns, exceptions, and examples for functions. Purpose and responsibilities for classes. Overview for modules.

2. API Documentation

Help developers use public interfaces correctly.

Per endpoint/function:

• Description (one sentence)
• Parameters with types and constraints
• Return values
• Error conditions
• At least one realistic example
• Authentication/authorization requirements (for APIs)

Checklist:

• All public functions/endpoints documented
• Parameter types and constraints specified
• Return values described
• Error conditions documented
• At least one example per function

3. Architecture Documentation

Help developers understand system design and make consistent changes.

Must include: System overview with component diagram, each component's responsibility, data flow, key design decisions with rationale, external dependencies, deployment architecture.

Checklist:

• System overview exists
• Component responsibilities documented
• Data flow explained
• Design decisions recorded with rationale

4. User Documentation

Help end-users accomplish tasks.

Types:

• Getting Started: Installation, first-run config, hello world, next steps
• How-To Guides: Goal-oriented, step-by-step, prerequisites, expected outcome
• Tutorials: Learning-oriented, guided, explains why not just how
• Reference: CLI commands, config options, env vars, troubleshooting

Checklist:

• Installation/setup instructions complete
• Getting started guide exists and works
• Major features have how-to guides
• Configuration options documented
• Troubleshooting section exists

Quality Standards

• Write for the intended audience; define jargon on first use
• Document actual behavior, not intended behavior
• Verify code samples compile/run
• 100% of public APIs documented; breaking changes have migration paths
• Update docs in the same commit as code changes
• Remove deprecated documentation

Anti-Patterns

• Documenting the obvious (x = 5 # set x to 5)
• Duplicating information across files
• Including example code that doesn't work
• Letting docs drift from code
• Writing novels when a sentence suffices

Documentation Output Examples

Good: Inline code comment -- explains the "why"

# Cache invalidation here because user permissions
# affect multiple downstream services. Without this,
# stale permissions persist for up to 5 minutes (TTL).
invalidate_permission_cache(user.id)

Bad: Inline code comment -- restates the "what"

x = x + 1  # increment x by 1

Good: API function docstring -- complete, has example

def create_user(name: str, email: str, role: str = "viewer") -> User:
    """Create a new user account.

    Args:
        name: Display name (1-100 characters).
        email: Must be unique across all accounts.
        role: One of "viewer", "editor", "admin". Defaults to "viewer".

    Returns:
        The newly created User object with generated ID.

    Raises:
        DuplicateEmailError: If email is already registered.

    Example:
        user = create_user("Alice", "alice@example.com", role="editor")
    """

Bad: API function docstring -- no types, no detail

def create_user(name, email, role="viewer"):
    """Creates a user."""

Integration

Referenced by: shipyard:documenter agent Pairs with: shipyard:shipyard-verification (documentation completeness is part of "done"), shipyard:code-simplification (clear code needs less documentation)