write-good-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Good Docs

撰写优质文档

Use this skill when documentation needs to become more useful, not merely longer.

当你需要让文档变得更实用，而非仅仅篇幅更长时，可以使用本技能。

Layout

目录结构

```
references/diataxis/
```
contains the Diataxis framework reference for classifying documentation into tutorials, how-to guides, reference, and explanation.
```
references/crafting-effective-readmes/
```
contains README templates, checklists, and style guidance.
```
references/ai-writing-tropes/
```
contains prose cleanup guidance for removing common AI-generated writing tells.

```
references/diataxis/
```
包含Diataxis框架参考内容，用于将文档分类为教程、操作指南、参考手册和说明文档。
```
references/crafting-effective-readmes/
```
包含README模板、检查清单和风格指南。
```
references/ai-writing-tropes/
```
包含文案清理指南，用于去除AI生成内容中常见的典型特征。

Reading Order

阅读顺序

Do not read the whole skill directory by default.

Classify the documentation task.
Load only the relevant reference area below.
Write or edit the docs.
Run the AI-writing trope check before finalizing prose.

默认无需阅读整个技能目录。

对文档任务进行分类。
仅加载下方相关的参考内容区域。
撰写或编辑文档。
在最终确定文案前，运行AI写作套路检查。

Task Router

任务指引

Writing or reorganizing documentation

撰写或重组文档

Start with Diataxis:

```
references/diataxis/compass.md
```

references/diataxis/how-to-use-diataxis.md

Then read the page-type reference that matches the job:

Tutorials:
```
references/diataxis/tutorials.md
```
How-to guides:
```
references/diataxis/how-to-guides.md
```
Reference:
```
references/diataxis/reference.md
```
Explanation:
```
references/diataxis/explanation.md
```

Use the boundary references when content is mixed:

```
references/diataxis/tutorials-how-to.md
```

references/diataxis/reference-explanation.md

references/diataxis/complex-hierarchies.md

从Diataxis框架开始：

```
references/diataxis/compass.md
```

references/diataxis/how-to-use-diataxis.md

然后阅读与任务匹配的页面类型参考：

教程：
```
references/diataxis/tutorials.md
```
操作指南：
```
references/diataxis/how-to-guides.md
```
参考手册：
```
references/diataxis/reference.md
```
说明文档：
```
references/diataxis/explanation.md
```

当内容混合时，使用边界参考内容：

```
references/diataxis/tutorials-how-to.md
```

references/diataxis/reference-explanation.md

references/diataxis/complex-hierarchies.md

Creating or improving a README

创建或优化README

Read:

references/crafting-effective-readmes/SKILL.md

references/crafting-effective-readmes/section-checklist.md

references/crafting-effective-readmes/style-guide.md

Choose the template that matches the audience:

Open source:

references/crafting-effective-readmes/templates/oss.md

Internal:

references/crafting-effective-readmes/templates/internal.md

Personal:

references/crafting-effective-readmes/templates/personal.md

Config:

references/crafting-effective-readmes/templates/xdg-config.md

阅读以下内容：

references/crafting-effective-readmes/SKILL.md

references/crafting-effective-readmes/section-checklist.md

references/crafting-effective-readmes/style-guide.md

选择与受众匹配的模板：

开源项目：

references/crafting-effective-readmes/templates/oss.md

内部文档：

references/crafting-effective-readmes/templates/internal.md

个人项目：

references/crafting-effective-readmes/templates/personal.md

配置文件：

references/crafting-effective-readmes/templates/xdg-config.md

Editing prose that sounds machine-generated

编辑机器生成风格的文案

Read:

```
references/ai-writing-tropes/SKILL.md
```
The specific trope file that matches the draft's problem: word choice, sentence structure, paragraph structure, tone, formatting, or composition.

阅读以下内容：

```
references/ai-writing-tropes/SKILL.md
```
与草稿问题匹配的特定套路文件：词汇选择、句子结构、段落结构、语气、格式或内容构成。

Diataxis Compass

Diataxis分类指南

Use this table to classify docs:

If the content...	...and serves the user's...	...then it belongs in...
informs action	acquisition of skill	a tutorial
informs action	application of skill	a how-to guide
informs cognition	application of skill	reference
informs cognition	acquisition of skill	explanation

Ask:

Is this about doing something or knowing something?
Is the user learning or working?

使用下表对文档进行分类：

如果内容...	...且服务于用户的...	...则属于...
指导行动	技能习得	教程
指导行动	技能应用	操作指南
传递认知	技能应用	参考手册
传递认知	技能习得	说明文档

思考以下问题：

内容是关于“做某事”还是“了解某事”？
用户是在学习还是在工作？

Defaults

默认规则

One page should have one primary job.
Tutorials teach by doing; they are safe, concrete, and teacher-led.
How-to guides help a competent user complete a real task.
Reference describes machinery accurately and tersely.
Explanation develops understanding, context, and tradeoffs.
READMEs answer the audience's first real questions.
Prose should be specific, direct, and varied enough to avoid obvious AI-writing patterns.

单个页面应仅有一个核心用途。
教程通过实践教学；内容安全、具体且由引导者主导。
操作指南帮助有能力的用户完成实际任务。
参考手册准确、简洁地描述机制。
说明文档培养理解、提供上下文并阐述权衡。
README需回答受众的首要实际问题。
文案应具体、直接且足够多样化，以避免明显的AI写作模式。

Sources

来源

Diataxis reference content comes from diataxis.fr by Daniele Procida.
README guidance is adapted from joshuadavidthomas/agent-skills/crafting-effective-readmes at commit
```
8730dd4838e423949e3ea5853aee05fdd2a33a08
```
.
AI-writing trope guidance is adapted from joshuadavidthomas/agent-skills/ai-writing-tropes at commit
```
8730dd4838e423949e3ea5853aee05fdd2a33a08
```
.

Diataxis参考内容来自Daniele Procida的diataxis.fr。
README指南改编自joshuadavidthomas/agent-skills/crafting-effective-readmes的提交
```
8730dd4838e423949e3ea5853aee05fdd2a33a08
```
。
AI写作套路指南改编自joshuadavidthomas/agent-skills/ai-writing-tropes的提交
```
8730dd4838e423949e3ea5853aee05fdd2a33a08
```
。