Back to Details

docs-quality

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Docs Quality

文档质量

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

使用本技能可产出准确、易读且内容完整的文档，满足新用户和资深用户的需求。

Workflow

工作流程

Read
```
docs/docs.json
```
first to understand IA, tabs, and existing groups.
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
Read the target page(s) and at least 2 neighboring pages to match tone and structure.
Load the
```
mintlify
```
skill and check whether a better component exists to represent the current content (instead of defaulting to plain Markdown).

Choose the page archetype (

overview

,

how-to

,

reference

,

guide

,

faq

,

troubleshooting

,

api

).

Apply the standards in
```
references/docs-quality-manual.md
```
.
If adding pages, update navigation in
```
docs/docs.json
```
.
Add cross-links to adjacent conceptual and reference pages.
Run checks from
```
references/review-checklist.md
```
.
Optionally run
```
scripts/docs_qc.sh
```
for quick structural linting.

首先阅读
```
docs/docs.json
```
以了解信息架构（IA）、标签页和现有分组。
编写前调研真实实现细节：
- 扫描
```
src/
```
  下的相关文件
- 阅读
```
/src/types.ts
```
  了解公开类型/选项/约定
- 阅读
```
/schema/isol8.config.schema.json
```
  了解配置键/默认值/枚举类型
阅读目标页面及至少2个相邻页面，以匹配文档的语气和结构。
加载
```
mintlify
```
技能，检查是否有更合适的组件来呈现当前内容（而非默认使用纯Markdown）。
选择页面原型（
```
overview
```
概览、
```
how-to
```
操作指南、
```
reference
```
参考文档、
```
guide
```
教程、
```
faq
```
常见问题、
```
troubleshooting
```
故障排查、
```
api
```
接口文档）。
遵循
```
references/docs-quality-manual.md
```
中的标准。
若添加新页面，需更新
```
docs/docs.json
```
中的导航配置。
添加至相邻概念性页面和参考页面的交叉链接。
执行
```
references/review-checklist.md
```
中的检查项。
可选择运行
```
scripts/docs_qc.sh
```
进行快速结构检查。

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
```

完整标准：
```
references/docs-quality-manual.md
```
页面模板：
```
references/page-templates.md
```
最终质检关卡：
```
references/review-checklist.md
```
Mintlify组件决策：
```
references/component-playbook.md
```
Ollama结构参考：
```
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.

每个页面必须包含清晰的
```
title
```
和
```
description
```
前置元数据。
参考页面需明确覆盖所有参数/标志。
示例必须真实且看起来可运行。
仅当代码片段有可验证的有意义可观察结果时，才包含预期输出/行为说明。
记录明确的输入/输出对时，需将它们放在同一个
```
<CodeGroup>
```
中（例如：
```
Command
```
命令 +
```
Expected output
```
预期输出），而非分散在不同的区块中。
当CLI、库和API示例同时出现时，使用
```
<Tabs>
```
标签页展示（每个界面对应一个标签页）。
对于内容较多的“相关页面”板块，使用
```
<CardGroup>
```
搭配描述性卡片，而非纯项目符号链接。
图表需在标准视口下可读（优先选择垂直/简洁的图表，而非宽且密集的图形）。
新增/修改的页面必须从相关页面添加交叉链接。
避免Markdown表格中的解析陷阱（尤其是行内代码单元格中未转义的竖线字符）。
内容丰富的页面末尾需添加与页面相关的FAQ和故障排查指南（若完整板块会冗余，可链接至专门的FAQ/故障排查页面）。
提示框需遵循用途：
```
<Warning>
```
用于风险/故障提示，
```
<Info>
```
用于操作上下文说明，
```
<Tip>
```
用于最佳实践建议，
```
<Note>
```
用于重要但无风险的注意事项，
```
<Check>
```
用于明确的成功确认。