隔一段时间重新打开一个项目，最需要的通常不是架构全景，而是几个朴素的答案：它解决什么问题，现在能做什么，以及从哪里开始。
项目说明可以先服务于这个场景。它不必很长，但最好让一个不记得所有细节的人，仍然能够顺利接手。
先给一个完整的起点
开头用两三句话说清用途和边界，接着给一个最小的使用例子。比起罗列所有参数，一段有输入、有操作、有结果的过程，更容易让读者建立方向感。
如果例子需要准备数据，就把准备过程也写出来。避免让读者在第一步就遇到一个没有解释的文件名，或一个只存在于作者电脑上的目录。
把易变的事实集中起来
版本要求、配置路径、运行方式，适合放在一个明确的位置。相同内容复制到多个章节，修改时就容易留下矛盾。
- 这是什么
- 如何开始
- 一个完整例子
- 常见问题
- 设计取舍与后续想法
目录只是起点。项目很小时，前面三项也许已经足够；等真正出现重复的问题，再增加对应的说明。
为决定保留一点上下文
“选择了什么”往往能从代码里看到，“为什么当时这样选”却很容易丢失。可以留一个简短的决定记录：当时的限制、考虑过的方案，以及最终接受的取舍。
好的说明，让下一次开始少一点猜测。
最后，试着按说明从头走一遍。省略的步骤通常不是写作时发现的，而是在真正使用时露出来的。