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
| Reference | Purpose | |--------------------------------------------------------------------------------------------------------| ----------------------------------------------- | | ../documentation/references/writing-style.md | Voice, tone, sentence structure | | ../documentation/references/content-patterns.md | Usage patterns, props structure, component patterns | | ../documentation/references/seo-optimization.md | SEO best practices, titles, descriptions, keywords, FAQs | | ../documentation/references/humanizer.md | Remove AI writing patterns, add voice and specificity |
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.mdnotform.md - Match URL structure: File name becomes the URL path
Writing Patterns
| Pattern | Example |
| ------------- |---------------------------------------------------------|
| Subject-first | "The useApp composable handles Fabric related logic." |
| Imperative | "Add the following to config.ts." |
| Contextual | "When relying on TypeScript, configure..." |
Modal Verbs
| Verb | Meaning |
| -------- | ----------- |
| can | Optional |
| should | Recommended |
| must | Required |
Component Patterns (WHEN to use)
| Need | Component |
| ----------------- |-------------------------------------|
| Info aside | > [!NOTE] |
| Suggestion | > [!TIP] |
| Caution | > [!WARNING] |
| Required | > [!IMPORTANT] |
| Multi-source code | ::: code-group and ends with ::: |
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