Yard Ruby Docs

yard-ruby-docs

yard ruby docs — automated documentation generation and maintenance using yard.

Yard Ruby Docs

Generate and maintain professional yard documentation that stays in sync with your code.

Overview

This skill automates yard ruby docs to keep documentation accurate, comprehensive, and up-to-date. It understands yard conventions and produces documentation that follows industry best practices.

Documentation debt is one of the biggest productivity killers in software teams. This skill tackles it by generating initial documentation from code, maintaining it through automated updates, and ensuring consistency across the entire project.

The output follows yard best practices and is optimized for both human readability and search engine discoverability. It handles edge cases like deprecated APIs, multi-version documentation, and cross-referenced content.

When to Use

Activate this skill when the user needs to:

Generate initial documentation for an undocumented codebase

Update existing docs after code changes

Set up a documentation site or system from scratch

Convert documentation between formats

Create API reference documentation from source code

Build onboarding guides for new team members

Core Capabilities

Auto-Generation

Scans source code to extract types, functions, classes, and their relationships. Generates structured documentation with descriptions, parameter tables, return types, and usage examples.

Template System

Provides customizable templates for different documentation types — API references, tutorials, how-to guides, and conceptual overviews. Templates follow the Diátaxis documentation framework.

Cross-Referencing

Automatically links related documentation pages, creates navigation structures, and maintains a consistent information architecture across the documentation site.

Version Management

Supports multi-version documentation, changelogs, and migration guides. Clearly marks deprecated features and provides upgrade paths.

Example Prompts

Users might ask:

"Generate API documentation for the src/api directory"

"Set up yard for our project with a getting-started guide"

"Create a migration guide from v2 to v3"

"Add JSDoc comments to all exported functions in the utils module"

"Build a searchable documentation site with yard"

Configuration

ParameterDefaultDescription

outputDir./docsDocumentation output directory

formatmarkdownOutput format (markdown, html, pdf)

includePrivatefalseInclude private/internal APIs in docs

themedefaultDocumentation theme

Best Practices

Document the why, not just the what — Code shows what it does; documentation should explain why it exists and when to use it

Keep examples runnable — Every code example should be copy-pasteable and produce the expected output

Use consistent terminology — Create a glossary and stick to it — inconsistent naming confuses readers

Write for your audience — API references for developers, tutorials for beginners, architecture docs for architects

Automate freshness checks — Run CI checks that flag documentation out of sync with code changes

Common Pitfalls

⚠️ Generating docs once and never updating them — stale docs are worse than no docs

⚠️ Over-documenting obvious code — focus documentation effort on complex or surprising behavior

⚠️ Not including examples — abstract descriptions without concrete examples are rarely useful

Output Format

Generates complete documentation files in markdown format, with navigation, cross-references, and search indexes. Ready to deploy to static hosting or integrate into existing documentation sites.