pragmatic-docs

务实的文档写作

编写尊重读者时间的文档：先解释为什么，再说明怎么做；用真实示例代替抽象描述，并且不避讳表达观点。本文受 Philip Greenspun 的方法启发：从核心理念入手，在上下文中展示真实代码，坦诚说明权衡，并在读者停止阅读之前停笔。

核心原则

1. 先讲为什么

每份文档都以核心理念开篇：这是什么、为什么存在，以及它解决了什么问题——用 1–3 个段落说明。如果你无法在三个段落内解释为什么值得关注，那就说明你还不够了解这个项目。

不好的写法：“此模块提供灵活、可扩展、企业级的解决方案……”

好的写法：“用户总是反复询问同样的五个问题。这个工具会自动回答这些问题，让维护者可以安心休息。”

2. 示例胜过抽象描述

一个真实示例胜过三段解释。展示实际命令、真实数据和真实输出。如果能展示具体场景，就不要编造 foo、bar、WidgetFactory 或 MyApp。

将代码融入叙述中——不要把它们隔离在单独的“示例”专区里。解释数据模型时，直接展示其架构。解释 CLI 时，在文中直接展示命令及其输出。

3. 观点很有价值

说出你的看法。“在这种情况下，X 比 Y 更好，因为……”比“X 和 Y 都是可选方案”更有用。承认权衡，推荐一种路径，并解释理由。读者可以不同意——但至少他们有明确的观点可供评估。

4. 坦诚说明局限

如果某项功能效果不佳，就直说。如果某种特定用例有更好的工具，就指出来。“如果你想按日期显示内容，/news 模块更合适”比假装自己的模块无所不能更有帮助。

5. 简洁是尊重

超过 300 行的 README 表明它应该拆分成单独的文档。不要用模板内容凑篇幅。每句话都必须有存在的价值。如果某个章节会是空的，或只包含一句无关紧要的话——就省略它。

---

文档结构

根据具体情况调整此结构。并非每个章节都适用于所有项目。绝不要为了填满模板而加入空章节或内容无关紧要的章节。

核心理念（必需）

始终包含。用 1–3 个段落说明：

• 这是什么？
• 为什么存在？它解决了什么问题？
• 它面向谁？

确保读者只读这一节就能决定是否继续阅读。不要使用没有即时解释的术语。不要写“旨在提供”——直接说明它的功能。

## What is this?

PhotoResize watches a directory for new images and resizes them to three
standard sizes for web delivery. We built it because our CMS required
manual image processing and editors were wasting 20 minutes per article
on something a script handles in 2 seconds.

快速开始（适用时）

提供从“我发现了这个工具”到“它在我的机器上运行了”的最短路径。命令最多 10 行。如果设置确实需要更长时间，快速开始部分应展示最顺畅的操作路径，并链接到详细的安装文档。

## Quick Start

pip install photoresize
photoresize watch ./uploads --output ./public/images

不要重复包管理器已经告诉用户的内容。不要列出所有标志。只需帮助用户成功运行即可。

内部原理（适用时）

介绍工具的内部工作方式——但只有在了解内部原理确实能帮助用户时才写。用叙述的方式解释架构决策，而不是把它写成规范。以实际架构或类型定义展示数据模型，不要用 UML 图或文字描述字段。

遵循 Greenspun 的写作模式：先展示数据模型，再解释其中值得关注的决策。你添加了哪些约束，为什么？你选择不存储什么，为什么？

## Under the Hood

The core data model is simple — one table per feed source, one table
for processed items:

    create table feed_sources (
        source_id   serial primary key,
        url         text not null unique,
        check_interval_minutes  integer default 60
    );

We chose not to store the full article body because it doubles storage
without clear benefit — the original URL is always one click away.

配置 / API（适用时）

只记录类型、签名或 --help 输出中不明显的内容。重点介绍：

• 不明显的默认值，以及选择这些默认值的原因
• 以出乎意料的方式相互影响的选项组合
• 90% 的用户都需要修改的那个配置项

不要在 Markdown 中重现整个类型系统或 CLI 的 --help 输出。这正是 --help 的用途。

示例（推荐）

展示真实场景，而不是抽象演示。每个示例都应解决某人实际遇到的问题。介绍每个示例时，用一句话说明何时适合使用这种模式。

### Resizing for social media cards

Social platforms crop unpredictably. Force a 2:1 aspect ratio and let
the smart-crop algorithm pick the focal point:

    photoresize convert photo.jpg --aspect 2:1 --smart-crop --output card.jpg

相关项目 / 模块（视情况而定）

提供指向替代工具或互补工具的交叉引用。每项都用一句话说明读者何时应改用它。这不是竞品列表，而是诚恳的使用建议。

## Related

- **ImageMagick** — better if you need arbitrary image transformations
  beyond resizing. We actually shell out to it under the hood.
- **sharp** — faster for Node.js projects; PhotoResize is for Python
  shops that want a CLI-first workflow.

限制 / 后续计划（可选）

仅当存在用户会遇到的真实且不明显的限制时才添加。不要列出你可能永远不会实现的功能路线图。

## Limitations

- No WebP output yet (tracking in #142)
- Smart cropping works poorly on images with multiple faces

---

写作规则

语气与风格

• 使用主动语态。“服务发送响应”，而不是“响应由服务发送”。
• 分享设计思路时可以使用第一人称。“我们选择 X 是因为……”或“我是在……之后构建这个项目的。”
• 像一位称职的工程师向另一位工程师解释问题那样写。不要像营销团队，也不要像法务部门。
• 如果幽默和个性自然流露，欢迎保留。不要刻意为之。

应包含的内容

• 说明做出决策的原因，而不只是决定了什么。
• 使用真实命令、真实数据和真实输出。
• 说明权衡——舍弃了什么，又获得了什么。
• 使用链接进行交叉引用，不要直接嵌入其他文档的内容。
• 展示代码块前，先用一句话说明每个代码块的内容。

应省略的内容

• 除 2–3 个真正有用的徽章（构建状态、版本、许可证）外，不要添加其他徽章。
• 少于 100 行的文档不要添加目录。
• 不要添加可通过 --help、类型签名或 JSDoc 获取信息的重复章节。
• 不要使用“旨在”“借助”“利用”“促成”或“企业级”等词语。
• 不要在 README 中内嵌自动生成的 API 文档——改为链接到相应文档。
• 不要保留空白模板章节（例如没有内容的“## 贡献”或“## 许可证”）。

文档中的代码

• 将代码直接放在叙述中，紧接着解释它的句子之后。
• 代码块使用项目实际采用的语言（不要用伪代码）。
• 代码片段应简短——理想长度为 5–15 行。如果更长，就说明一次展示的内容过多。
• 用注释标明值得关注的行，不要注释显而易见的内容。

长度指南

文档	目标长度	备注
README.md	50–200 行	门面文档。简洁明了。详细内容通过链接提供。
模块文档	30–150 行	一个模块 = 一个关注点 = 一份文档。
CONTRIBUTING.md	30–80 行	环境搭建 + 约定 + PR 流程。无需更多。
架构文档	100–300 行	核心理念 + 数据模型 + 关键决策。

如果文档超过目标长度，可以考虑拆分，而不是删减。两份重点明确的文档胜过一份冗长的文档。

---

应避免的反模式

模板坟场。 一份有 15 个章节、其中一半写着“TODO”或只有一句话的 README。每个章节都必须有存在的价值。

API 镜像。 文档重复列出代码中已经可见的每个函数签名和参数类型。应记录行为、决策和注意事项，而不是签名。

企业腔。“本项目旨在提供全面、可扩展的解决方案……”——没人会这样说。直接说明它的作用。

追求面面俱到的陷阱。 试图一开始就记录每个边界情况和选项。充分说明 80% 的常见用法，把边界情况留给 issue 和讨论处理。

把 README 写成更新日志。 README 大部分内容都在罗列变更历史。记录变更历史应使用 CHANGELOG.md 和 git log。

徽章墙。 README 顶部放了 12 个徽章，其中一半已经失效。挑选 2–3 个真正有用的即可（CI 状态、npm 版本、许可证）。

---

何时应用此技能

在以下情况下使用此方法：

• 为任何软件项目创建新的 README.md
• 改进或重写现有文档
• 在 docs/ 目录中编写模块级文档
• 创建 CONTRIBUTING.md、架构文档或设置指南
• 记录新功能、API 或服务
• 审查文档的简洁性和实用性

根据项目类型调整

库/软件包： 以快速入门（安装 + 基本用法）开篇。“核心理念”部分说明何时应选择此库而不是其他替代方案。

CLI： 以最常用的一条命令开篇。展示真实的终端输出。记录那些无法从 --help 中直接理解的标志。

API/服务： 以“核心理念”（此服务的功能）开篇。展示真实的请求/响应示例。在“底层原理”部分介绍数据模型。

框架： 以“核心理念”（此框架秉持的理念）开篇。快速入门部分应直达“hello world”。“底层原理”部分介绍其思维模型。

内部工具： 更坦诚地说明限制。受众无法改用竞争产品，因此应帮助他们绕过已知问题。