Back to Details

docs-writing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Writing

技术文档编写

52 rules across 9 categories for documentation quality. Focuses on concrete issues with concrete fixes.
涵盖9大类别、共52条提升文档质量的规则，聚焦具体问题并提供明确修复方案。

Doc Writing/Audit Workflow

文档编写/审核工作流

Copy and track this checklist during the audit:
text
Doc writing/audit progress:
- [ ] Step 1: Determine doc type (tutorial, how-to, reference, explanation) and audience
- [ ] Step 2: Run CRITICAL checks (voice and tone, structure and organization)
- [ ] Step 3: Run HIGH checks (clarity and language, code examples)
- [ ] Step 4: Run MEDIUM+ checks for remaining categories in scope
- [ ] Step 5: Report findings with file:line and concrete fixes
  1. Audit only changed files unless a full sweep is requested.
  2. Identify the doc type (tutorial, how-to, reference, explanation) and intended audience to select relevant categories.
  3. Load rule files progressively by category prefix — read only what applies.
  4. Prioritize CRITICAL and HIGH findings before medium-priority polish.
  5. After fixes, rerun the relevant rules before finalizing.
在审核过程中可复制并跟踪以下检查清单：
text
Doc writing/audit progress:
- [ ] Step 1: Determine doc type (tutorial, how-to, reference, explanation) and audience
- [ ] Step 2: Run CRITICAL checks (voice and tone, structure and organization)
- [ ] Step 3: Run HIGH checks (clarity and language, code examples)
- [ ] Step 4: Run MEDIUM+ checks for remaining categories in scope
- [ ] Step 5: Report findings with file:line and concrete fixes
  1. 除非要求全面检查，否则仅审核有变更的文件。
  2. 确定文档类型（教程、操作指南、参考文档、说明文档）及目标受众，以选择相关类别。
  3. 按类别前缀逐步加载规则文件——仅阅读适用内容。
  4. 优先处理CRITICAL（关键）和HIGH（高优先级）问题，再进行中等优先级的优化。
  5. 修复完成后，在最终定稿前重新运行相关规则检查。

Rule Categories by Priority

按优先级划分的规则类别

PriorityCategoryImpactPrefixRules
1Voice & ToneCRITICAL
voice-
4
2Structure & OrganizationCRITICAL
structure-
10
3Clarity & LanguageHIGH
clarity-
6
4Code ExamplesHIGH
code-
7
5Formatting & SyntaxMEDIUM-HIGH
format-
8
6Navigation & LinkingMEDIUM-HIGH
nav-
6
7Scanability & ReadabilityMEDIUM
scan-
2
8Content HygieneMEDIUM
hygiene-
6
9Review & TestingLOW-MEDIUM
review-
3
优先级类别影响程度前缀规则数量
1语气与语调CRITICAL
voice-
4
2结构与组织CRITICAL
structure-
10
3清晰度与语言表达HIGH
clarity-
6
4代码示例HIGH
code-
7
5格式与语法MEDIUM-HIGH
format-
8
6导航与链接MEDIUM-HIGH
nav-
6
7易扫描性与可读性MEDIUM
scan-
2
8内容整洁度MEDIUM
hygiene-
6
9审核与测试LOW-MEDIUM
review-
3

Quick Reference

快速参考

Read only what is needed for the current scope:
  • Category map and impact rationale: 
    rules/_sections.md
  • Rule-level guidance and examples: 
    rules/<prefix>-*.md
Example rule files:
rules/voice-defaults.md
rules/structure-diataxis.md
rules/clarity-defaults.md
Each rule file contains:
  • Why the rule matters
  • Incorrect example
  • Correct example
仅阅读当前场景所需内容：
  • 类别映射及影响说明：
    rules/_sections.md
  • 规则级指导与示例：
    rules/<prefix>-*.md
示例规则文件：
rules/voice-defaults.md
rules/structure-diataxis.md
rules/clarity-defaults.md
每个规则文件包含：
  • 规则的重要性说明
  • 错误示例
  • 正确示例

Review Output Contract

审核输出规范

Report findings in this format:
markdown
undefined
请按以下格式提交审核结果：
markdown
undefined

Documentation Audit Findings

Documentation Audit Findings

path/to/file.md

path/to/file.md

  • [CRITICAL] 
    voice-defaults
    : Passive voice obscures who performs the action.
    • Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."
  • [CRITICAL] 
    voice-defaults
    : Passive voice obscures who performs the action.
    • Fix: Rewrite "The configuration is loaded by the server" as "The server loads the configuration."

path/to/clean-file.md

path/to/clean-file.md

  • ✓ pass

- Group findings by file.
- Use `file:line` when line numbers are available.
- State issue and propose a concrete fix.
- Include clean files as `✓ pass`.
  • ✓ pass

- 按文件分组展示问题。
- 若有行号，使用`file:line`格式标注。
- 说明问题并提出明确的修复方案。
- 将无问题的文件标记为`✓ pass`。