docs-quality（文档质量）

Docs Quality

Use this skill to produce documentation that is accurate, scannable, and complete enough for first-time and advanced users.

Workflow

1. Read docs/docs.json first to understand IA, tabs, and existing groups.
2. Research source-of-truth implementation details before writing:

- scan relevant files under src/ - read /src/types.ts for public types/options/contracts - read /schema/isol8.config.schema.json for config keys/defaults/enums

1. Read the target page(s) and at least 2 neighboring pages to match tone and structure.
2. Load the mintlify skill and check whether a better component exists to represent the current content (instead of defaulting to plain Markdown).
3. Choose the page archetype (overview, how-to, reference, guide, faq, troubleshooting, api).
4. Apply the standards in references/docs-quality-manual.md.
5. If adding pages, update navigation in docs/docs.json.
6. Add cross-links to adjacent conceptual and reference pages.
7. Run checks from references/review-checklist.md.
8. Optionally run scripts/docs_qc.sh for quick structural linting.

Which reference file to load

• Complete standards: references/docs-quality-manual.md
• Page skeletons: references/page-templates.md
• Final QA gate: references/review-checklist.md
• Mintlify component decisions: references/component-playbook.md
• Ollama structural references: references/ollama-reference-notes.md

Non-negotiables

• Every page must have clear title and description frontmatter.
• Use explicit parameter/flag coverage for reference pages.
• Examples must be realistic and runnable-looking.
• Include expected output/behavior only when the snippet has a meaningful observable result to validate.
• When documenting explicit input/output pairs, group them in a single <CodeGroup> (for example: Command + Expected output) instead of separating them into distant blocks.
• When CLI + Library + API examples appear together, present them in <Tabs> (one tab per interface).
• For substantial “Related pages” sections, use a <CardGroup> with descriptive cards instead of plain bullet links.
• Diagrams must be readable on standard viewport (prefer vertical/simple over wide dense graphs).
• New/changed pages must be cross-linked from related pages.
• Avoid parser pitfalls in Markdown tables (especially unescaped pipe characters in inline code cells).
• End substantial pages with page-relevant FAQ and troubleshooting guidance (or links to dedicated FAQ/troubleshooting pages when full sections would be redundant).
• Callouts must follow intent: <Warning> for risk/breakage, <Info> for operational context, <Tip> for best-practice recommendations, <Note> for important but non-risk caveats, <Check> for explicit success confirmation.