文档不是写完就扔的摆设
很多团队的文档是这样的：项目初期花一周写了份「系统设计文档」，之后就再没人打开过。半年后新人接手，文档和实际代码早就对不上，只能靠口口相传。
技术文档工程要做的，就是把文档从一次性的交付物，变成跟着代码一起活下来的工程资产。
文档最大的问题不是写得不好，而是写完就不再更新，最后变成一份误导后人的档案。
本文核心知识点
- 文档即代码文档跟代码放在一起版本管理。
- 架构可视化用图让人一眼看懂系统。
- C4 模型从上下文到代码的分层视图。
- 少而准好图只画当前要说明的。
- 文档治理让文档长期不过时。
文档即代码：跟代码一起演进
文档即代码的核心做法很简单：把文档当成代码来管理——和代码放在同一个仓库、用同样的版本控制、改代码时顺手改文档、走同样的评审流程。
| 做法 | 好处 |
|---|---|
| 文档跟代码同仓库 | 改代码的人顺手改文档 |
| 随代码一起评审 | 文档更新不被遗忘 |
| Markdown 编写 | 开发者写起来没负担 |
# 文档即代码的简单规矩
- 新功能先写一段说明再写代码
- 改接口时顺手更新对应文档
- 文档跟代码一起评审、一起合并
# 把「写文档」从额外任务变成开发的一部分。这样文档就不再是项目初期的一锤子买卖，而是和系统一起长大的活文档。
架构可视化：让人看懂系统
再详尽的文字文档，也不如一张好图直观。架构可视化的目的，是让一个没接触过系统的人，花十分钟就能说清这个系统由哪些部分组成、它们怎么连起来。
- 用方框表示组件，用连线表示调用关系。
- 分层表达：外部、服务、数据，一眼看清。
- 图上只画当前要讲清楚的那部分。
好的架构图不是越全越好，而是让看图的人快速建立正确的整体印象。
C4 模型：分层视图
C4 模型把架构图分成四个由粗到细的层次，不同的人看不同层次，避免一张图塞满所有人需要的信息。
| 层次 | 看什么 |
|---|---|
| 上下文 | 系统在整个业务里的位置和外部关系 |
| 容器 | 系统由哪些可部署单元组成 |
| 组件 | 某个容器内部的模块划分 |
| 代码 | 具体的类和接口细节 |
面向新人先看上下文和容器，面向开发再深入组件和代码——不同听众配不同粒度的图。
好架构图：少而准，多而不乱
一张塞了几十个方框的「系统全貌图」，往往没人看得下去。好的架构图克制而准确。
# 画架构图的小规矩
- 一张图只讲一个主题
- 只画和当前问题相关的组件
- 连线表达真实的依赖关系
- 图旁配一两句话说明为什么这么画
# 少而准，比多而全更有用。架构图的目的不是展示你多懂系统，而是让看图的人快速建立正确的心智模型。
文档治理：让它不过时
文档即代码解决了「怎么写」，但还要解决「怎么让它长期不过时」。简单的几条治理规矩就够。
- 每次改架构，对应那张图必须一起更新。
- 标注文档最后更新时间，过期的一眼可见。
- 定期回顾，删掉已经过时的说明。
当更新文档成为流程的一部分，而不是额外的负担，文档才不会悄悄腐烂。
让系统被读懂、被继承
技术文档工程与架构可视化的最终目的，是让系统不只是能跑起来，还能被人读懂、被新人继承。
- 文档跟代码一起演进，不再过时。
- 分层架构图让不同人各取所需。
- 新人接手时，文档是第一手入口。
当一个系统被清晰地画出来、写下来、维护起来，它就不再是少数几个人脑子里的秘密，而是团队可以共同继承的资产。