make-documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Make Documentation

文档制作

When to Use

适用场景

Writing or updating a README.md, architecture note, changelog, or release notes
Auditing existing project docs before adding missing documentation
Drafting customer-facing security guidance or partner-sensitive article prose from source material
Writing live access, reproduction, lab interface, workstation/server, or operator runbooks
Documenting notebooks, generated notebooks, or table-producing notebook workflows
Writing WSL, local, Docker, or environment-specific install docs
Writing agent operation manuals, role files, peer-status contracts, or AI-readable workflow docs
Producing diagram documents only when the user explicitly asks or the project already uses them

编写或更新README.md、架构说明文档、变更日志或发布说明
在补充缺失文档前审核现有项目文档
根据原始资料起草面向客户的安全指南或合作伙伴敏感的文章内容
编写实时访问、问题复现、实验室界面、工作站/服务器或运维人员运行手册
记录笔记本、生成的笔记本或生成表格的笔记本工作流
编写WSL、本地环境、Docker或特定环境的安装文档
编写Agent操作手册、角色文件、对等状态契约或AI可读的工作流文档
仅当用户明确要求或项目已在使用图表文档时，才生成图表文档

When NOT to Use

不适用场景

Writing API reference documentation
Creating or updating AGENTS.md. Use
```
agents-md
```
, even when the broader request also includes other docs.
Generating diagram files by default when prose or tables are sufficient

编写API参考文档
创建或更新AGENTS.md。即使更广泛的请求还包含其他文档，也请使用
```
agents-md
```
技能处理该文件。
在文字或表格足以满足需求时默认生成图表文件

Workflow

工作流程

Run scripts/audit_documentation.py for new docs, large rewrites, doc moves, missing-doc investigations, or unclear structure. For tiny explicit edits, inspect the target file and nearby docs directly.
Choose only the deliverables justified by the user's request and the audit. Do not generate a fixed documentation bundle by default.
Route by document type: use references/guide-readme.md for
```
README.md
```
, references/guide-architecture.md for
```
docs/architecture.md
```
or the repo's existing equivalent, references/guide-ai-ingestion.md when the user says the document is for agents/AI ingestion, references/guide-agent-ops-docs.md for role/workflow docs consumed by agents, references/guide-access-runbook.md for live access, reproduction, operator, lab interface, or capability ledgers, references/guide-notebook-documentation.md for notebook explanations, references/guide-install-runbook.md for WSL/local/Docker install docs, references/guide-security-article.md for partner-sensitive security articles, and references/guide-changelog.md for
```
CHANGELOG.md
```
or release notes. If AGENTS.md becomes part of scope, switch that file to
```
agents-md
```
instead of expanding this skill.
Use references/guide-diagrams.md only when the user explicitly asks for diagram docs or the project already maintains them.
For large docs, iterative reports, feature inventories, concept framing, or evidence-audit amendments, load references/source-discovery-and-heading-stability.md before writing.
For concept or strategy docs, include a visible first usable workflow before architecture depth so the reader can execute a small slice before absorbing the model.
Keep the output source-backed and terse. Preserve user-provided terminology and avoid generic rewrites that change domain meaning or connotation.
Preserve earlier requested documentation when later implementation work touches the same notebooks, docs, or folders. Re-open touched docs before finishing if there is a risk an unrelated implementation change removed prior documentation.
Review the result with references/review-checklist.md before finishing.

当创建新文档、大幅重写文档、迁移文档、调查缺失文档或结构不清晰时，运行scripts/audit_documentation.py。对于微小的明确修改，直接检查目标文件及周边相关文档即可。
仅选择符合用户请求和审核结果的交付内容。默认情况下不要生成固定的文档包。
根据文档类型选择对应指南：编写
```
README.md
```
时使用references/guide-readme.md，编写
```
docs/architecture.md
```
或仓库中现有等效架构文档时使用references/guide-architecture.md，当用户说明文档用于Agent/AI摄取时使用references/guide-ai-ingestion.md，编写供Agent使用的角色/工作流文档时使用references/guide-agent-ops-docs.md，编写实时访问、问题复现、运维人员、实验室界面或能力台账相关文档时使用references/guide-access-runbook.md，编写笔记本说明文档时使用references/guide-notebook-documentation.md，编写WSL/本地/Docker安装文档时使用references/guide-install-runbook.md，编写合作伙伴敏感的安全文章时使用references/guide-security-article.md，编写
```
CHANGELOG.md
```
或发布说明时使用references/guide-changelog.md。如果AGENTS.md被纳入范围，请切换为使用
```
agents-md
```
技能处理该文件，而非扩展本技能的使用范围。
仅当用户明确要求图表文档或项目已在维护图表文档时，才使用references/guide-diagrams.md。
对于大型文档、迭代报告、功能清单、概念框架或证据审核修订，在开始编写前加载references/source-discovery-and-heading-stability.md。
编写概念或策略文档时，在深入介绍架构之前，先提供一个清晰可用的初始工作流，以便读者在理解完整模型前可以先执行一小部分内容。
输出内容需基于原始资料且简洁明了。保留用户提供的术语，避免使用会改变领域含义或内涵的通用改写。
当后续实现工作涉及相同的笔记本、文档或文件夹时，保留之前已完成的文档内容。如果存在无关的实现变更可能删除原有文档的风险，请在完成前重新检查相关文档。
在完成前，使用references/review-checklist.md对结果进行审核。

Anti-Patterns

反模式

Wrong: summarize a notebook from a generated README, review packet, AI commentary, or stale comments. Correct: trace executable cells, imports, widgets, SQL, configs, and outputs, then write the short explanation.
Wrong: write folder-contract docs after a move from memory. Correct: audit the tree and update parent and child docs together.
Wrong: duplicate validators, schemas, CLIs, table lists, or source-of-truth modules while documenting around implementation. Correct: scan for existing source-of-truth assets and link to them.
Wrong: leave workflow docs tied to VS Code, one editor, or one UI unless the user explicitly requested that. Correct: state editor-independent start state and execution plane.
Wrong: keep meta labels such as
```
review packet
```
,
```
AI-generated summary
```
, or
```
analysis artifact
```
in human-facing docs unless they are required schema fields. Correct: use natural section names that match the audience.
Wrong: label demo-only flags or filters as future product interfaces. Correct: separate test scaffolding from durable user or agent interfaces.

错误做法：根据生成的README、审核包、AI评论或过时注释总结笔记本内容。正确做法：追踪可执行单元格、导入项、小部件、SQL语句、配置和输出结果，然后编写简短说明。
错误做法：凭记忆编写文件夹契约文档。正确做法：审核目录结构并同步更新父文档和子文档。
错误做法：在围绕实现编写文档时重复编写验证器、模式、CLI、表格列表或可信源模块。正确做法：扫描现有可信源资产并添加链接。
错误做法：将工作流文档绑定到VS Code、单一编辑器或单一UI，除非用户明确要求。正确做法：说明独立于编辑器的起始状态和执行环境。
错误做法：在面向人类的文档中保留
```
review packet
```
、
```
AI-generated summary
```
或
```
analysis artifact
```
等元标签，除非它们是必填的架构字段。正确做法：使用符合受众习惯的自然章节名称。
错误做法：将仅用于演示的标志或过滤器标记为未来产品界面。正确做法：将测试框架与持久的用户或Agent界面区分开。

Deterministic Tools

确定性工具

Tool	Use When	Outcome
scripts/audit_documentation.py	You need a deterministic inventory before writing docs	Current-state documentation audit

工具	使用场景	输出结果
scripts/audit_documentation.py	在编写文档前需要确定性的文档清单时	当前状态的文档审核报告

References

参考文档

references/guide-readme.md - README workflow
references/guide-architecture.md - architecture documentation
references/guide-ai-ingestion.md - compact machine-ingestion documentation mode
references/guide-agent-ops-docs.md - role, directive, peer-status, and execution-plane docs for agents
references/guide-access-runbook.md - live access, reproduction, interface, and capability ledgers
references/guide-notebook-documentation.md - notebook explanation and runnable-order preservation
references/guide-install-runbook.md - environment-specific install docs
references/guide-security-article.md - partner-sensitive security article workflow
references/guide-changelog.md - changelog and release notes
references/guide-diagrams.md - opt-in diagram workflow only
references/review-checklist.md - review pass before finishing
references/source-discovery-and-heading-stability.md - large-doc source discovery and stable heading checks
references/ascii-art-standards.md - diagram formatting standards when diagrams are in scope

references/guide-readme.md - README工作流
references/guide-architecture.md - 架构文档指南
references/guide-ai-ingestion.md - 紧凑的机器摄取文档模式
references/guide-agent-ops-docs.md - 供Agent使用的角色、指令、对等状态和执行环境文档指南
references/guide-access-runbook.md - 实时访问、问题复现、界面和能力台账指南
references/guide-notebook-documentation.md - 笔记本说明及可执行顺序保留指南
references/guide-install-runbook.md - 特定环境安装文档指南
references/guide-security-article.md - 合作伙伴敏感安全文章工作流指南
references/guide-changelog.md - 变更日志和发布说明指南
references/guide-diagrams.md - 仅可选启用的图表工作流指南
references/review-checklist.md - 完成前的审核清单
references/source-discovery-and-heading-stability.md - 大型文档的源文件发现及标题稳定性检查指南
references/ascii-art-standards.md - 当图表在范围内时的图表格式标准