Back to Details

doc-generator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Generator

文档生成器

Documentation must be grounded in specific claims rather than abstract adjectives. We avoid filler phrases like "In today's fast-paced world" and focus on delivering useful information directly. Each claim should be supported by evidence, such as specific version numbers or request rates, rather than vague descriptors like "comprehensive."
文档必须基于具体的表述，而非抽象形容词。我们避免使用诸如“在当今快节奏的世界中”这类填充语句，专注于直接传递有用信息。每个表述都应有证据支撑，例如具体的版本号或请求速率，而非“全面的”这类模糊描述。

Core Writing Principles

核心写作原则

We prioritize authorial perspective and active voice to maintain a consistent team tone. This involves explaining the reasoning behind technical choices, such as selecting one database over another, rather than providing neutral boilerplate. Bullets should be used sparingly for actionable summaries; multi-line bullet waterfalls should be converted to short paragraphs to preserve nuance.
我们优先采用作者视角和主动语态，以保持团队一致的语气。这包括解释技术选择背后的原因，比如选择某一数据库而非另一数据库，而非提供中立的通用模板。项目符号应仅用于可操作的摘要；多行项目符号列表应转换为短段落，以保留细节。

Vocabulary and Style

词汇与风格

Avoid business jargon and linguistic tics like mirrored sentence structures or excessive em dashes. We use the imperative mood for docstrings (e.g., "Validate input") and strictly avoid humanizing non-living constructs like code.
Instead ofUse
fallbackdefault, secondary
leverageuse
utilizeuse
facilitatehelp, enable
comprehensivethorough, complete
避免使用商务术语和诸如镜像句式或过多破折号这类语言习惯。我们在文档字符串中使用祈使语气（例如："Validate input"），严格避免将代码等非生命体拟人化。
避免使用建议使用
fallbackdefault, secondary
leverageuse
utilizeuse
facilitatehelp, enable
comprehensivethorough, complete

9. Limit Humanizing Constructs

9. 避免拟人化表述

"Lives under," "speaks to," and similar phrases only make sense for living things.
“依赖于”“与……对话”这类表述仅适用于生命体。

10. Imperative Mood for Docstrings

10. 文档字符串使用祈使语气

"Validate" not "Validates" (per PEP 257, pydocstyle, ruff).
使用"Validate"而非"Validates"（符合PEP 257、pydocstyle、ruff规范）。

Required TodoWrite Items

必备TodoWrite事项

  1. doc-generator:scope-defined
    - Target files and type identified
  2. doc-generator:style-loaded
    - Style profile applied (if available)
  3. doc-generator:content-drafted
    - Initial content created
  4. doc-generator:slop-scanned
    - AI markers checked
  5. doc-generator:quality-verified
    - Principles checklist passed
  6. doc-generator:user-approved
    - Final approval received
  1. doc-generator:scope-defined
    - 已确定目标文件和类型
  2. doc-generator:style-loaded
    - 已应用风格配置文件（若有）
  3. doc-generator:content-drafted
    - 已完成初始内容创作
  4. doc-generator:slop-scanned
    - 已检查AI生成标记
  5. doc-generator:quality-verified
    - 已通过原则检查清单
  6. doc-generator:user-approved
    - 已获得最终批准

Mode: Generation

模式：生成

For new documentation:
适用于创建新文档：

Step 1: Define Scope

步骤1：定义范围

markdown
undefined
markdown
undefined

Generation Request

生成请求

Type: [README/Guide/API docs/Tutorial] Audience: [developers/users/admins] Length target: [~X words or sections] Style profile: [profile name or "default"]
undefined
类型：[README/指南/API文档/教程] 受众：[开发者/用户/管理员] 长度目标：[约X词或X节] 风格配置文件：[配置文件名或“默认”]
undefined

Step 2: Load Style (if available)

步骤2：加载风格配置（若有）

If a style profile exists:
bash
cat .scribe/style-profile.yaml
Apply voice, vocabulary, and structural guidelines.
若存在风格配置文件：
bash
cat .scribe/style-profile.yaml
应用语气、词汇和结构指南。

Step 3: Draft Content

步骤3：起草内容

Follow the 10 core principles above. For each section:
  1. Start with the essential information
  2. Add context only if it adds value
  3. Use specific examples
  4. Prefer prose over bullets
  5. End when information is complete (no summary padding)
遵循上述10项核心原则。对于每个章节：
  1. 从关键信息入手
  2. 仅在能增加价值时添加上下文
  3. 使用具体示例
  4. 优先使用散文而非项目符号
  5. 信息传递完整后即结束（无需冗余总结）

Step 4: Run Slop Detector

步骤4：运行冗余内容检测器

Skill(scribe:slop-detector)
Fix any findings before proceeding.
Skill(scribe:slop-detector)
修复所有检测到的问题后再继续。

Step 5: Quality Gate

步骤5：质量门禁

Verify against checklist:
  • No tier-1 slop words
  • Em dash count < 3 per 1000 words
  • Bullet ratio < 40%
  • All claims grounded with specifics
  • No formulaic openers or closers
  • Authorial perspective present
  • No emojis (unless explicitly requested)
对照检查清单验证：
  • 无一级冗余词汇
  • 每1000词中破折号使用次数少于3次
  • 项目符号占比低于40%
  • 所有表述均有具体依据
  • 无公式化开头或结尾
  • 采用作者视角
  • 无表情符号（除非明确要求）

Mode: Remediation

模式：修复

For cleaning up existing content:
Load: 
@modules/remediation-workflow.md
适用于优化现有内容：
加载：
@modules/remediation-workflow.md

Step 1: Analyze Current State

步骤1：分析当前状态

bash
undefined
bash
undefined

Get slop score

获取冗余内容评分

Skill(scribe:slop-detector) --target file.md
undefined
Skill(scribe:slop-detector) --target file.md
undefined

Step 2: Section-by-Section Approach

步骤2：逐节处理

For large files (>200 lines), edit incrementally:
markdown
undefined
对于大文件（超过200行），逐步编辑：
markdown
undefined

Section: [Name] (Lines X-Y)

章节：[名称]（第X-Y行）

Current slop score: X.X Issues found: [list]
Proposed changes:
  1. [Change 1]
  2. [Change 2]
Before:
[current text]
After:
[proposed text]
Proceed? [Y/n/edit]
undefined
当前冗余评分：X.X 发现的问题：[列表]
建议修改：
  1. [修改1]
  2. [修改2]
修改前：
[当前文本]
修改后：
[建议文本]
是否继续？[是/否/编辑]
undefined

Step 3: Preserve Intent

步骤3：保留原意

Never change WHAT is said, only HOW. If meaning is unclear, ask.
绝不修改内容的核心信息，仅调整表述方式。若含义不明确，请询问确认。

Step 4: Re-verify

步骤4：重新验证

After edits, re-run slop-detector to confirm improvement.
编辑完成后，重新运行slop-detector以确认评分提升。

Docstring-Specific Rules

文档字符串特定规则

When editing code comments:
  1. ONLY modify docstring/comment text
  2. Never change surrounding code
  3. Use imperative mood ("Validate input" not "Validates input")
  4. Brief is better - remove filler
  5. Keep Args/Returns structure if present
编辑代码注释时：
  1. 仅修改文档字符串/注释文本
  2. 绝不修改周围代码
  3. 使用祈使语气（"Validate input"而非"Validates input"）
  4. 简洁为佳 - 删除冗余内容
  5. 保留Args/Returns结构（若已存在）

Module Reference

模块参考

  • See 
    modules/generation-guidelines.md
    for content creation patterns
  • See 
    modules/quality-gates.md
    for validation criteria
  • 内容创作模式请参考
    modules/generation-guidelines.md
  • 验证标准请参考
    modules/quality-gates.md

Integration with Other Skills

与其他Skill的集成

SkillWhen to Use
slop-detectorAfter drafting, before approval
style-learnerBefore generation to load profile
sanctum:doc-updatesFor broader doc maintenance
Skill使用场景
slop-detector起草完成后，批准之前
style-learner生成前加载配置文件
sanctum:doc-updates用于更广泛的文档维护

Exit Criteria

退出标准

  • Content created or remediated
  • Slop score < 1.5 (clean rating)
  • Quality gate checklist passed
  • User approval received
  • No emojis present (unless specified)
  • 已完成内容创作或修复
  • 冗余评分<1.5（清洁等级）
  • 已通过质量门禁检查清单
  • 已获得用户批准
  • 无表情符号（除非明确指定）