架构师不只是”懂技术”或”脑子聪明”

架构师到底是什么？
架构师不只是”懂技术”或”脑子聪明”——这些特质只是帮你走到资深级别的基础。也不只是”能设计并交付高可用、结构优良的系统”（虽然这也很重要）。

在我看来，核心差别就一个：

高级开发工程师懂得将代码部署到由代码构成的系统中，而架构师则懂得将想法部署到由人构成的系统里。

这话听起来可能像空洞的比喻，但我保证不是。

先说明白：我不是说架构师”擅长沟通”或”人缘好”（虽然这两点确实有用），也不是用华丽辞藻强调”软技能很重要”（虽然软技能确实关键）。我想表达的是，架构师除了懂”部署机器和应用的流程”，更掌握一套高效、可复用的流程来组织和传递想法。他们清楚，单靠推送代码能解决的问题有限；真正关键的问题，需要不同岗位、不同视角的人提供输入、协作推进，最终达成共识才能解决。

换句话说，在大多数公司里，想启动一个持续数月的项目、重构某个 Web 服务，或是为新产品选定编程语言，都得获得其他开发者和负责人的认可。软件生命周期里最大的瓶颈，从来都不是代码本身——而是人的问题：沟通不畅、难以说服他人、决策卡壳。

所以，架构师要想产生影响力，就得一迭代接一迭代、一季度接一季度地推进这些事。怎么才能稳定地让”对的人在对的时间聚到一起，讨论对的话题”？有没有能对”人”生效的”传输协议”或”基础设施即代码”工具？

还真有。

而且不止一种：Confluence、飞书、语雀、Notion、…诸如此类。只要你会列点说明、能加文档间的链接，就能”部署”自己的想法。在大多数公司里，想做成一件事，最高效的方式就是：写一份文档，分享给关心这件事的人，然后倾听他们的反馈。

但很多程序员对自己的写作能力没信心。要从自己熟稔的领域（编程，好坏自有代码说话）切换到陌生的领域（写作，好坏全看读者判断），确实不容易。所以下面我会给个”速成指南”：不用太多知识，就能帮你自信地写出不错（甚至优秀）的文档，无论你之前会不会写。你不需要有英语学位，不用认识”idempotent（幂等）”这种词，甚至不用用母语写——只要学几个小技巧就行。

好文档的核心原则
这是我对文档写作的”信条”：

作为一个”文档控”，我更看重： 先把想法记下来，别纠结结构 倡导文档文化，而非走流程式记录 聚焦核心信息，而非套用模板 记录特定时间点的信息，而非频繁更新
我特意让它和敏捷宣言的句式相近——右边的做法有价值，但左边的更关键。

后面我会详细展开其中几点，包括不同类型文档该怎么搭结构，但请记住第一点和第三点：与其卡在”找完美格式”上，不如先把你知道的写下来；而且不同文档的格式也不用统一，重点是”当下呈现这些信息，哪种方式最有效”，而不是”以前这么做过”。

怎么写文档？
哪怕你没怎么写过技术文档，也能写出高质量的内容。有个简单却超好用的技巧，几乎能让你写的任何文档都变好用：用项目符号（bullet points）。

项目符号简直是神器：它能让你专注于信息的完整性和逻辑性，不用纠结句子通顺与否、文采好不好。读技术文档的人，都想快速找到信息——其实衡量文档好坏的最佳标准之一，就是读者能多快找到所需信息并停止阅读。如果 10 秒内找到答案就关掉，那这文档就是成功的。而项目符号信息密度高、易浏览，刚好适配这个需求。

比如我刚才那两段话，用项目符号写是这样的：

项目符号超适合技术写作
帮你聚焦信息完整性和逻辑性
不用太多写作技巧
让文档更易浏览
信息几乎没丢，但篇幅只占原来的 25%，写起来也更轻松。这就是为什么项目符号是架构师的”最佳搭档”。

第二个超有用的技巧是加标题（headers）。如果你的信息没法用寥寥几个项目符号说清，那就值得拆成几个带明确标题的小节。

比如我写的大部分文档，开头都会有个”背景” section。作用是提供话题相关的历史、业务领域或既定约束，顺便加些链接。这些信息你天天接触，可能烂熟于心，但其他读者会需要”帮他们回忆”；就算是一年后你自己回头看，也会感激当初写的背景。

当然，对话题很熟悉的人，完全可以快速扫过甚至跳过”背景”部分——这就是标题的好处：能让读者更快找到自己要的信息，忽略无关内容。（如果标题太多，想优化体验，加个带链接的”目录”也很好用。)

要是一开始不知道该加什么标题，先随便按顺序列项目符号就行。之后把这些点按逻辑分组，再给每组贴个标签——这和写代码其实很像：你可能先写个 200 行的方法，跑通之后，通常会重构：拆成多个步骤，把重复逻辑抽成函数。

最要避免的是”大段密密麻麻的文字”。你文档需要争取注意力的人，往往都是时间最紧张的人。要是发过去一篇四页纸的”小作文”，他们很可能根本没时间读。但如果是结构清晰的项目符号列表，他们就能快速滚动浏览，提取所需信息，有空再回复。

文档写完后该做什么？
信息都写好后，建议做个”合理性检查”：发给你常合作的同事，让他们指出不对劲或看不懂的地方。然后根据反馈修改、调整结构或重述内容。

要记住：大多数文档更像”一次性的 Bash 脚本”，而不是”需要持续维护的 SaaS 应用”。一旦文档完成了它的使命，你可能再也不会更新它。作为架构师，一年写一百份文档都很正常，根本没时间全维护一遍。

这一点带来两个启示：第一，要确保每份文档”足够好用”，哪怕以后逐渐过时，回头看也能用上——现在多花点功夫，之后就能彻底忘了它，直到需要时再找。第二，要让人能轻松看出文档的”撰写时间”，以及”同一时期还有哪些相关文档”。只有明确知道”这文档有多旧”，”特定时间点的记录”才有价值。

我组织文档的方式可能有点反直觉。大多数人会按”话题”分类：这个功能一个文件夹，那个功能一个文件夹。但这样会导致一堆”看似平等、实则价值不一”的文件夹：有的装满最新、最相关的文档，有的五年没更新过，还有的新旧文档混在一起，甚至互相矛盾，还看不出先后顺序。

所以我几乎所有文档都按”时间”排序：先按年份，再按迭代周期（sprint）。这样能清晰看到”时间线”。比如在 Confluence 里，我会给每个团队或产品建一个”空间”（其他工具可能叫”工作区”“维基”或”文档集”——高层次的分类还是需要的），但每个空间里的文件夹结构是这样的：

📄 概览
📄 架构
📁 2025
📁 1 月第一迭代
📄 提案：SSO 登录功能
📄 APP-132 用户会话研究
📁 1 月第三迭代
📄 APP-135 支持为指定客户配置 SSO 登录
📁 2 月第一迭代
📄 SSO 登录与用户角色的冲突问题
📄 开发预判：角色权限复杂度将上升
当然，少数”高层次文档”确实需要持续维护。比如有人想了解产品概况，那有个最新的”首页”和架构图会很有用。但大多数文档都有”有效期”：时间越久，相关性越低。

你可能会问：”这不反常识吗？我通常找的是’某个项目/功能的文档’，不是’2020 年 3 月的文档’啊。“我的回答是：“不是有搜索框吗？“按话题分类就像”给软糖分类”——没人能达成共识。这意味着你写文档时，要花时间想”该放哪个文件夹”；找文档时，又要在错的文件夹里翻半天才能找到对的。这就像”按逻辑而非字母顺序整理 CSS 属性”：把 left 和 top 放一起可能感觉舒服，但没实际用处。CSS 按字母排序更快、更简单，还完全够用；文档按时间排序，道理也一样。

而且说到底，“搜索”通常才是正确选择。浏览适合用来”了解有哪些文档”，但如果找特定信息，很容易漏掉那些标题看似无关、实则包含所需信息的文档。而搜索又快，还能把所有匹配结果都列出来。按时间组织文档，其实是”逼着”大家用搜索（本来就该这么做）；而且点进搜索结果时，能立刻知道文档的撰写时间，以及当时还在推进哪些事——上下文一下子就全了。

文档经过同行评审并发布后，最后一步是”复制链接分享出去”：如果这篇文档替代或补充了其他文档，就去那篇文档里加个链接；如果和工单系统的任务相关，也贴过去；最后，把链接发给需要反馈、审批或共识的人。