文档 - 架构师的“编程语言”

小坤探游架构笔记

发布于 2025-10-11 11:31:33

700

文章被收录于专栏：小坤探游架构笔记小坤探游架构笔记

点击上方小坤探游架构笔记可以订阅哦

今天偶然在墙外网站看到一篇关于架构师编写文档技巧的文章《Documents: The architect’s programming language》, 我个人觉得写得挺不错, 对此我将文章部分核心内容记录并分享出来.

为何文档是架构师的“编程语言”

从上述图中我们可以看到作为一名架构师, 其需要与开发、运维、产品以及上级管理者之间存在紧密的协作, 那么当面向不同的角色的时候, 要如何向它们表达自己的想法, 并将自己的想法部署在生产环境中呢?

在回答上述问题之前, 《Documents: The architect’s programming language》首先向我们传递一个关于开发与架构师之间的本质区别, 即:

Senior developers know how to deploy code to systems made of code.
Architects know how to deploy ideas to systems made of people.

我谈谈自己对上述的理解与思考: 其一是开发人员的核心能力是 “将代码部署到代码构成的系统”，而架构师的核心价值在于 “将想法部署到由人构成的体系”。这种差异并非源于技术深度，而是解决问题的维度不同; 其二是要想将自己的想法部署到由人构成的体系系统中, 那么我们就需要拥有一项工具, 这项工具就是将架构师的想法向不同的角色人员传传递信息, 这个工具就是文档.

那为何文档如此重要呢? 这是因为在与不同的人员进行组织协作中，“让正确的人在正确时间讨论正确的事” 无法通过技术工具实现，而文档（如 Confluence、Notion 等工具创建的内容）是最可靠的 “传输协议”, 如下:

文档能打破信息壁垒，让不同角色（开发、产品、管理层）快速对齐认知；
文档可沉淀反馈、形成共识，避免口头沟通的模糊性与遗忘性；
文档能跨越时间周期，为后续决策、问题追溯提供依据。

文档写作原则与技巧

文章《Documents: The architect’s programming language》提出的写作原则出类似 “敏捷宣言” 的文档理念，强调 “优先事项” 而非绝对规则：

1. JOTTING THINGS DOWN over worrying about how to structure them.

第一条是优先 “随手记录”，而非纠结结构 —— 先捕捉核心信息，再优化格式，避免因追求完美而搁置；

2. A CULTURE OF DOCUMENTATION over box-checking behavior

第二条是优先 “文档文化”，而非 “打卡式记录”—— 鼓励主动通过文档分享思考，而非为满足流程要求应付了事；

3. THINKING ABOUT WHAT’S RELEVANT over using a template

第三条是优先 “聚焦相关性”，而非套用模板 —— 根据信息内容选择合适形式，不被固定模板限制；

4. POINT-IN-TIME DOCUMENTATION over constant updates

第四条是优先 “时点文档”，而非 “持续更新”—— 多数文档只需完成当下使命，无需长期维护，避免精力浪费。

由此可见文章提倡 “快速动手、专注核心内容、让文档自然存在即可”.

那么如何编写文档呢? 主要有三个技巧:

1. bullet points. - 使用项目符号

怎么理解呢? 这个我们交给AI来解答, 这里我举了一个例子, 比如我们想要描述架构师的核心能力, 我们一般会从这样的方式进行表达如下:

上述表达有什么特点呢? 信息完整, 但是我们需要仔细阅读信息才能抓住重点, 那么如果采用Bullet points的方式, 那么这个时候我们表达架构师的核心能力如下:

这个时候我们看到采用项目符号的方式一眼就能够抓住重点, 方便浏览和对比.由此可见采用Bullet points的作用有:

Help you focus on completeness and structure, 焦聚信息的完整性与结构化.
Don’t require as much writing skill, 无需太多的写作技巧.
Make documents easier to skim, 能够让阅读者快速从文档中略读提取关键信息.

2.Headers - 采用标题拆分

同样地我们继续描述架构师的核心能力, 如果采用headers的方式, 那么此时我们的文档编写方式如下:

从上述例子其实就是将我们编写的文档进行合理分段, 我想对于这类相信我们大多数都能够掌握.

3. Avoid Wall of Text - 避免文字墙

其实讲大白话就是避免讲述一大段密集、没有结构或者停顿的文字, 导致读者失去耐心, 同样我们也可以借助AI举一个例子说明:

那么改进之后如下:

总结起来就是:

用 headers → 分层组织内容，方便浏览。
用 bullet points 或分段 → 打散信息，避免长段落。
关键字加粗 → 突出重点信息。

当我们采用上述编写文档之后呢, 其实还有一步就是处理我们的文档, 也就是文档完成之后的动作:

1. Once you’ve got all the necessary information written down, consider doing a sanity check.

其一是先做 “合理性检查”：完成初稿后，发送给密切协作的同事，修正逻辑漏洞、补充模糊信息；

为什么需要做检查呢? 在文章中有这样的一段描述, 我觉得挺有道理的:

Keep in mind that most documents are more like one-off Bash scripts than living SaaS applications. Once a document has done its job, you probably won’t ever update it again. As an architect, you can easily write a hundred documents a year; you definitely don’t have time to maintain them all.

This has two implications. First, you should make sure each document is good enough to be useful later, even as it gradually goes obsolete. It’s worth putting in some extra effort now so you can forget about it until it comes up again. Second, you should make it easy to tell when the document was originally written, and conversely, easy to find documents that were written around the same time. Point-in-time documentation is a lot more useful when it’s obvious how out-of-date it is.

就是说我们编写的文档很多时候就像一次性编写Bash脚本一样而不是像Sass应用程序经常发生动态变化, 因此很有必要将我们的文档进行完善, 主要有两个理由: 其一是即使文档过时了, 但你无法保证它在将来的某一天就能派上用场, 这其实就是一个经验积累的过程; 其二是我们需要为文档增加时间的标识以方便识别, 同样地还需要保证它在我们建立的文档库能够更快地实现“搜索”, 即遇到某个问题, 我在大脑中产生与问题相关的关键词, 那么我利用这个关键词进行搜索就能得到我想要的文档信息.

因此我认为检查的目的一是让文档保持完善, 保留当初设计的细节; 其次是便于搜索可随时调用查阅分析.

2. by year and then by sprint

正如上述所说, 文档要便于搜索, 因此考虑将文档按时间归档文档（按年、按 sprint）：例如以 Confluence 为例，建立 Space 或 Wiki，然后在里面按 2025 → “Jan 1 Sprint” → 文档。这样组织比按主题分类更易保持时间线可视化，避免文件生命周期混乱. 如下: