Docs

Documentation Skill

Generate and maintain documentation that meets or exceeds the standard set by the best open-source Rails/JS projects (Inertia Rails, Vite Ruby, Rails itself).

Before You Start

Read these reference files (located in the references/ subdirectory next to this SKILL.md file) before proceeding:

1. Quality Standard — references/quality-standard.md — tiered audit checklist (Must-Have / Expected / Differentiator)
2. Documentation Templates — references/templates.md — structural skeletons for each doc type
3. Competitive Landscape — references/competitive-landscape.md — benchmarks against peer projects

Workflow

Step 1: Assess the current state

• Scan the repo for existing docs: docs/, README.md, CHANGELOG.md, CONTRIBUTING.md, inline code comments, Wiki, and any hosted doc site config (VitePress, Docusaurus, Jekyll, etc.)
• Identify what exists, what is outdated, and what is missing
• Compare against the Quality Standard reference above

Step 2: Determine scope

If the user gave a specific target (e.g., /docs $ARGUMENTS), focus there. Otherwise, present a prioritized gap analysis:

1. Critical gaps - Missing README sections, no quick start, no API reference
2. High-value improvements - Outdated guides, missing migration/upgrade docs, no troubleshooting
3. Polish - LLMs.txt, cookbook/recipes, configuration reference, contributor guide improvements

Ask the user which items to tackle (or do all if they say so).

Step 3: Generate or rewrite documentation

Follow these principles for ALL documentation:

Voice and Style

• Direct and concise. Lead with what the reader needs. No filler.
• Show, don't tell. Every concept gets a code example. Prefer real-world examples over contrived ones.
• Progressive disclosure. Quick start first, then deeper guides, then API reference. Layer complexity.
• Avoid em dashes (use commas, parentheses, or separate sentences instead).
• Use second person ("you") for guides and tutorials. Use third person for API references.
• Prefer active voice. "Run bundle install" not "The bundle should be installed."

Structure by Doc Type

README.md (the front door):

• One-liner description + badges
• "What is this?" in 2-3 sentences
• Quick install (copy-paste ready)
• Minimal "Hello World" example that works
• Link table to deeper docs
• Requirements / compatibility matrix
• Community links (Slack, Discussions, Stack Overflow)
• Contributing pointer
• License

Quick Start Guide (< 15 minutes):

• Prerequisites with exact version requirements
• Step-by-step, numbered instructions
• Every command is copy-paste ready
• "You should see..." verification checkpoints after key steps
• Link to "next steps" at the end

Conceptual Guides (explain "why" and "how"):

• Start with a one-paragraph summary of what the reader will learn
• Use diagrams (Mermaid or ASCII) for architecture and data flow
• Break into logical sections with clear headings
• End each guide with "Related" links

API / Helper Reference:

• One page per module or helper group
• Signature, parameters table, return value, exceptions
• At least one usage example per method
• For Ruby: follow YARD conventions (@param, @return, @example)
• For TypeScript: follow TSDoc conventions (@param, @returns, @example)

Configuration Reference:

• Table format: option name, type, default, description
• Group by category
• Include example config file (annotated with comments)

Migration / Upgrade Guide:

• Version-to-version, with exact steps
• "Breaking changes" section at top
• "Deprecations" section
• Automated migration commands if available
• Before/after code comparisons

Troubleshooting / FAQ:

• Problem statement as the heading (what the user sees or encounters)
• Cause explanation (1-2 sentences)
• Solution with exact commands or code
• "Still stuck?" pointer to community support

LLMs.txt (AI-friendly docs):

• /llms.txt with a structured overview and links to key pages
• /llms-full.txt with complete documentation in a single Markdown file
• Follow the llms.txt specification: title, description, sections with URLs
• Include on every docs page: "Are you an LLM? View /llms.txt for optimized documentation"

Step 4: Cross-reference and link

• Every guide should link to related guides
• Every API method mentioned in a guide should link to its reference page
• Add a "See also" or "Related" section at the bottom of each page
• Verify no dead links (check file paths exist)

Step 5: Review with the user

Present the generated docs and ask:

• "Does this match how your project actually works?"
• "Any terminology or naming I got wrong?"
• "Anything missing for your users?"

Targeting Specific Files

When invoked as /docs <target>:

• If <target> is a file path: generate/update docs FOR that code file (inline comments, module-level docs, method docs)
• If <target> is a directory: generate/update docs for the entire module
• If <target> is a doc type keyword (e.g., "readme", "api", "quickstart", "migration", "troubleshooting", "llms.txt", "audit"): generate that specific doc type
• If <target> is "audit": run a full gap analysis against the Quality Standard reference above and report findings

Language-Specific Conventions

Ruby

• Use YARD doc format for all public methods and classes
• @param name [Type] description
• @return [Type] description
• @raise [ExceptionClass] when condition
• @example with realistic usage
• @see for cross-references
• Document @option for hash parameters

TypeScript / JavaScript

• Use TSDoc for TypeScript, JSDoc for JavaScript
• @param name - description
• @returns description
• @throws {ErrorType} description
• @example blocks with realistic usage
• Export documentation: what is public API vs. internal
• Document generic type parameters

Markdown Docs

• Use ATX headings (#, ##, ###) not Setext
• Fenced code blocks with language identifiers (ruby, typescript, ```bash)
• Use reference-style links for repeated URLs
• Tables for configuration options and API parameter lists
• Admonitions for warnings and tips (use blockquote style: > **Note:** ... or > **Warning:** ...)