把复杂问题写清楚

技术文章最常见的问题并不是信息太少，而是读者不知道这些信息之间是什么关系。

先给读者一张地图

面对复杂主题，可以先说明四件事：

• 我们要解决什么问题；
• 哪些部分不在本文范围内；
• 系统由哪些关键部分组成；
• 读完之后读者应该能做什么。

然后再逐层展开细节。这样读者即使暂时不理解某个术语，也知道它在整体中的位置。

示例要回答一个问题

代码示例应尽可能短，但不能短到失去上下文：

type Article = {
  title: string
  draft: boolean
}

const canPublish = (article: Article) => !article.draft

这个例子只表达一件事：草稿状态是发布流程中的明确门槛。更复杂的权限、审阅和部署逻辑应在后续段落分别解释。

最终，清楚的技术写作与有效的读书笔记很相似——都需要区分原始材料、自己的理解和能够指导行动的结论。