Documentation

Documentation Skill

This skill provides comprehensive guidelines for AI coding assistants working on documentation.

When to Use

• Adding a new plugin, feature, or option
• Changing plugin behavior or API signatures
• Fixing bugs that affect code generation
• Writing or updating functionalities/component/composable documentation
• Optimizing documentation for search engines

What It Does

• Create clear, concise, practical documentation optimized for developer experience
• Optimize content for search engines and developer intent
• Structure content for maximum scannability and engagement

Writing Standard

Override: When writing documentation, maintain proper grammar and complete sentences. The "sacrifice grammar for brevity" rule does NOT apply here.

Documentation must be:

• Grammatically correct
• Clear and unambiguous
• Properly punctuated
• Complete sentences (not fragments)

Brevity is still valued, but never at the cost of clarity or correctness.

Available References

Load based on context:

• Writing prose → ../documentation/references/writing-style.md
• Props, options, usage patterns → ../documentation/references/content-patterns.md
• Optimizing for search → ../documentation/references/seo-optimization.md
• Reviewing or editing finished prose → ../documentation/references/humanizer.md

Language and Tone

• Use the US spelling. For example, use license, not licence.

Naming Conventions

• Use kebab-case: how-to-do-thing.md
• Be descriptive: multipart-form-data.md not form.md
• Match URL structure: File name becomes the URL path

Writing Patterns

Modal Verbs

Component Patterns (WHEN to use)

Headings

• H1 (#): No backticks
• H2-H4: Backticks work fine

Links and Cross-References

• Internal links: Use relative paths: /plugins/plugin-ts/
• Anchor links: Link to specific sections: /plugins/plugin-ts/#output-path
• External links: Use full URLs with descriptive text
• Placement: Add links section at the very end of the document

Images and assets

• Location: docs/public/
• Reference: Use relative paths from markdown files
• Formats: Use optimized formats (webp/png/jpg)
• Sizing: Keep file sizes reasonable
• Naming: Use descriptive names: plugin-react-query-example.png

Checklist

• Active voice (85%+)
• Present tense
• 2-3 sentences per paragraph
• Explanation before code
• Validate frontmatter syntax
• Run humanizer pass: remove AI patterns, add voice and specific details