stijnvanhulle Documentation skill
Writing 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
- Write clear, practical documentation aimed at the developer reading it
- Match the words developers search for
- Structure content so a reader can skim it and still find the answer
Writing standard
When writing documentation, keep 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 |
|---|---|
| references/writing-style.md | Voice, tone, sentence structure |
| references/content-patterns.md | Usage patterns, props structure, component patterns |
| references/seo-optimization.md | SEO practices, titles, descriptions, keywords, FAQs |
To remove AI writing patterns and add voice, use the humanizer skill.
Load based on context:
- Writing prose → references/writing-style.md
- Props, options, usage patterns → references/content-patterns.md
- Optimizing for search → references/seo-optimization.md
- Reviewing or editing finished prose → the humanizer skill
Language and tone
- Use the US spelling. For example, use license, not licence.
Naming conventions
File names are kebab-case (how-to-do-thing.md) and descriptive: multipart-form-data.md, not
form.md. The file name becomes the URL path, so pick it with that in mind.
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
Keep backticks out of the H1. From H2 down they are fine.
Links and cross-references
Internal links use relative paths (/plugins/plugin-ts/), and anchors point at a section
(/plugins/plugin-ts/#output-path). External links carry the full URL and descriptive text.
Put the links section at the very end of the document.
Images and assets
Images live in docs/public/ and are referenced with relative paths from the markdown file.
Use webp, png, or jpg, keep the files small, and name them for what they show:
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