软件开发文档：属于架构师的开发语言

从初级开发者到高级/首席开发者，职业路径通常清晰明了。你越擅长编码，越精通让编码更高效的技术与非技术技能，晋升就越快。但一旦到了高级阶段，面前就会出现一条重大分岔口。

许多人选择管理路线。这是扩大影响力、向上攀登的好办法。但缺点是，你不可避免地会减少编程时间——很多工程经理根本没时间写代码——如果你和我一样，这就没法接受。过去你埋头把复杂流程转化为优美抽象的时间，会变成开会、为团队扫清障碍、调解分歧、给HR填表格。这工作有挑战也重要，但完全不同。

另一个常见选项是架构师路线。这让你能继续深陷代码之中，同时扩大影响力、利用资历。在很多公司，架构师路线和管理路线的薪酬、职级晋升机会差不多，两条路都可能通向高管职位（比如CTO）。

但相比之下，架构师路线似乎定义模糊。转做人员管理后，日常工作彻底变了：日程、团队结构都不同，工作成果衡量方式也完全不同。但做架构师和做高级开发者很像：在IDE里写代码、评审拉取请求、讨论部署流水线、数据结构这些事。那架构师到底有什么不同？换句话说，想证明自己准备好做架构师了，该怎么做？

什么是架构师？

不只是知识渊博或聪明——那是你走到今天的原因。也不只是交付resilient（抗风险）、设计良好的系统——虽然这也很重要。

在我看来，区别主要在一点：

高级开发者知道如何把代码部署到由代码构成的系统里。

架构师知道如何把想法部署到由人构成的系统里。

这话听着像空洞的比喻，但我保证不是。

澄清一下：我不是说架构师只是沟通好、善合作（虽然这两点也重要），也不是用漂亮话强调软技能重要（虽然它们确实重要）。我是说，架构师掌握有效、可复用的流程，用来组织和部署想法——这超越了组织和部署机器、应用的流程。他们知道光靠提交代码能达成的有限；最重要的问题需要不同视角、不同职级的人的输入、协作和共识。

换句话说，多数公司的大多数工程师，没经过其他开发者和领导同意，就没法启动耗时数月的项目、重写Web服务，或给新产品选编程语言。软件生命周期的最大瓶颈和代码无关，是人的问题：沟通、说服、决策。

所以要想产生影响，架构师必须一次次、一季度季地让这些事发生。怎么可靠地把对的人在对的时间聚在一起，谈对的事？有没有对人类有效的传输协议或基础设施即代码工具？

巧了，还真有。

其实是几种工具：Confluence、GoogleDocs、Notion、XWiki、BookStack……你懂的。只要会用要点符号、能在文档间加链接，就能部署想法。在大多数组织里，做成事最有效的方法是：写份文档，发给最可能关心的人，听他们的反馈。

但很多程序员对自己的写作能力没信心。从你擅长的、质量自证的事（编程），切换到你不熟悉、质量靠读者判断的事（写作），很难。所以下面是个速成课：够用的信息，帮你自信写出好（甚至很好）的文档，不管你是谁。不用英语学位，不用会拼“幂等”（idempotent），甚至不用母语写。只需学几个技巧。

后面我会细说其中几点，包括不同类型文档的结构思路，但记住第一和第三点：写下你知道的，比卡在找对格式上强；格式也不必每份文档都一样。专注当下要呈现的信息，别管以前怎么写的。

怎么写文档

就算你没多少技术写作经验，也能写出优秀文档。有个简单却极其有效的窍门，能提升你写的几乎所有文档：用要点符号。

要点符号很神奇。它让你进入“完整、有条理”的思维，而非纠结句子流畅和风格。读技术文档的人想快速找信息——事实上，文档好坏的最佳衡量标准之一，是人们多久停下阅读。如果他们10秒内找到需要的就离开，就是成功。要点符号信息密集、易浏览，是完美工具。

把最后两段改成要点符号看看：

•要点符号适合技术写作

•帮你专注完整性和条理性

•不需要太多写作技巧

•让文档更易浏览

同样的信息，只占四分之一页面，写起来也更轻松。所以要点符号是架构师最好的朋友。

第二有用的技巧是用标题。除非信息能用很少要点说清，否则值得用有意义的标题分节。

比如，我写的大部分文档开头都有“背景”部分。目的是提供主题的历史、业务领域或预设约束的信息和链接。你可能凭记忆知道这些（因为你天天在做），但其他读者会感谢这点提醒。一年后你回头看自己的文档，也会感激。

当然，对主题已有深入了解的人可以略过或跳过“背景”部分。标题的好处就在这：让人更容易找到想要的信息片段，忽略无关的。（如果标题超过五六个想进一步优化，加个带链接的目录很好。）

一开始不知道用什么标题？先按想到的顺序写要点，再把它们分组、标标签。这和编程没太大区别：你可能先写200行的方法草稿，跑通后再重构，拆成步骤、把通用模式提取成函数。

要避免的主要是一大段密密麻麻的文字。通常最需要看你文档的人，时间也最紧。发给他们一篇四页的文章，他们很可能永远没时间读完。而一组条理清晰的要点，能让他们滚动浏览、抓取需要的信息，有空时再回复。

写完文档做什么

记下所有必要信息后，先做合理性检查。发给常合作的同事，请他们指出不对或不明白的地方，再用反馈澄清、重组或改写。

记住，多数文档更像一次性Bash脚本，而非持续更新的SaaS应用。文档完成使命后，你可能永远不会再更新。作为架构师，你一年能轻松写上百份文档，肯定没时间维护所有。

这有两层意思。第一，确保每份文档足够好，以后有用——哪怕它慢慢过时。现在多花点功夫，以后忘了它直到再次需要时再找。第二，让人容易看出文档最初写于何时，反过来也容易找到同期写的文档。记录特定时间点的文档，要是能明显看出多旧，会更有用。

我的做法可能反直觉。多数人按主题整理文档：这个功能的文件夹，那个功能的文件夹。但这会导致一堆看似平等的文件夹，价值却不等。有的装满近期高相关文档，有的五年没新文档，还有的新旧混在一起，有些直接矛盾，一时看不出顺序。

注意：少数高层文档值得持续维护。如果有人想了解产品概况，有个更新的着陆页和架构图就好。但多数文档有保质期：随时间推移越来越不相关。

你可能问：“这不是和人们想的相反吗？我通常找特定项目或功能的文档，不是2020年3月发生的事。”我的回答：“有搜索框啊。”按主题整理文档像给jellybeans（软糖）分类：没人能就正确方式达成一致。这意味着你写每份文档时，都得浪费时间想该放哪；找文档时，得在错文件夹里翻半天。就像按逻辑而非字母顺序整理CSS属性：left和top放一起感觉好，但实际没用。对CSS，字母顺序更快、更简单、永远够用。对文档，时间顺序同理。

再说，搜索通常是对的。浏览适合发现有哪些文档，但找特定信息时，很容易漏掉标题不直接相关的文档。搜索则快，能找出所有匹配项。时间顺序的整理方式，几乎逼着人们用搜索——他们就该这么干。点击搜索结果时，能立刻知道文档何时写的、当时还发生了什么。

文档经同行评审、发布后，最后一步是拿链接到处发。如果它覆盖或扩展了另一份文档，在那份文档里加链接。如果关联了问题跟踪单，也加上。最后，发给需要反馈、批准或共识的人。

附录：高影响力的文档类型

以下是工程组织里最有效的几种文档。

架构概览

目的：帮他人快速了解系统结构和设计。

受众：系统所有利益相关者——经理、开发者、运维工程师、产品经理等。

何时撰写：建新系统或重构现有系统前。现有系统难理解时也适用。

内容：描述系统主要组件（数据库、应用、云服务、负载均衡器等）及交互方式。也可描述内部组件（数据模型、类等），但避免细节过多。

结构：可以是带圆柱、方框、箭头等符号的图，分章节的多页文档，或嵌套要点列表。常见格式有arc42、C4。

如何统筹想法：最新的架构概览（哪怕有点旧）能帮贡献者形成系统心理模型，以便在其上构建、排障、推理。也帮领导、运维工程师理解如何交付、成本多少、与现有系统如何交互——这对最初获批至关重要。

小贴士：记住，随手记下要点比纠结结构重要。别为严格格式或用对所有符号焦虑（除非你想）。存在的不完美架构文档，比不存在的完美文档好。

开发设计

目的：获取对你打算写代码的反馈；在写一堆半成品代码（最终可能被扔掉）前，暴露未知和复杂点。

受众：团队其他开发者；未来想了解系统演进的开发者。

何时撰写：开始任何非琐碎编码任务前。也可在开始后，发现看似简单实则复杂时补写。

内容：细节程度你定。不用说显而易见的，但包含足够信息让其他开发者指出错误假设，推荐你可能不知道的现有逻辑/模式。

结构：列明后续步骤。比如：类A加方法做X，新建类B存Y相关数据，建数据库迁移做Z等。也可加“待解决问题”部分（开始前需处理的）或“替代方案”部分（让队友权衡的不同实现）。

如何统筹想法：开发设计帮开发者共享知识、保留系统核心模式和抽象。也为系统如何变成现在这样留永久记录。如果团队不做结对/群体编程，开发设计能提供类似好处，还帮未来贡献者学系统。

小贴士：听着像假话，但真的：写文档越多，写代码越少。文档能避免误解、错误假设、设计失误——这些会导致PR反复修改、重写。也能避免花时间在没结果的探索性编码上。

项目提案

目的：沟通项目价值和成本，以便分配时间和资金。

受众：领导和产品经理。

何时撰写：规划会议临近时，或看到有意义改进/扩展公司产品系统的机会时。

内容：总结领导评估项目优先级所需的一切。为什么重要？影响谁？要多久？等等。

结构：几个清晰标注的部分，如背景、待解问题、提议方案、用户影响、预估工程投入。

如何统筹想法：项目提案是耗时数月、影响大的项目的起点。它为整个团队设定路线图。

小贴士：让提案容易被说“是”——让技术和非技术利益相关者都看懂。记住别人不会总想着你在做的事，所以你需要比想象中更多的背景。提前做些研究：数据挖掘看影响多少用户，打听问题多烦人，读其他团队/公司类似项目的做法。

开发者预测

目的：提出可能比预期糟的结果（尤其你凭经验特别有预见性的），并建议应对方式。

受众：业务决策的利益相关者。

何时撰写：做出让你作为工程师觉得冒险或可能失望的决策时。

内容：先总结决策原因和决策者希望达成的目标。解释你为何认为负面结果可能发生，描述这些结果。然后建议缓解方式，即便决策最终不变。

结构：有条理的文档，含决策、动机、问题、可能结果、解决方案等部分。

如何统筹想法：开发者预测帮你分享专业预见，让人们思考计划的隐患。也让组织在出问题时能快速巧妙应对，而非反复掩盖。计划失败时，你的预测能成“北极星”，显出预期与结果的差距。

小贴士：保持中立语气，别像危言耸听。考虑多种可能，别试图扭转全局；只是指出冰山，建议应对方法。

技术菜单

目的：启动新应用时减少决策时间。

受众：开发团队或组织。

何时撰写：规划项目时，对用什么技术有分歧。

内容：针对某类技术（编程语言、运行时、框架、平台等），聚焦你和同事最倾向的选项。比较各自优势：组织对它的熟悉度（不仅是构建，还有部署维护）？招到喜欢它的开发者容易吗？开源生态健康、文档好吗？普通开发者从零到有可用应用多快？它是否鼓励跨代码库可识别的标准、结构、模式？需要时性能好吗？全面了解技术和非技术利弊后，建议每种何时用——比如一种默认用于Web服务，另一种用于无服务器函数，再一种用于原型和内网应用。

结构：对比表，后附几种场景的明确建议。

如何统筹想法：技术菜单帮就“如何构建”达成共识，让开发者启动有用技术时不陷于“这个还是那个”的争论。也能挑战因传统而非适用性/流行度留存的公司默认选项。

小贴士：别鼓吹个人偏好。写菜单时，让用过不同技术的开发者多轮反馈，他们的意见和你的一样重要。让团队达成一致，比选绝对“最好”的技术更重要。

问题陈述

目的：就如何解决或规避问题快速达成共识。

受众：项目利益相关者。

何时撰写：遇到无明显解决方案的问题，需组织明确决策时。

内容：用简单语言解释问题本质。若有明确业务影响，描述（或估算）范围和严重性。多数问题涉及两个及以上无法同时满足的约束；若如此，明确这些约束及矛盾原因。然后提几种可行方案，总结各方案利弊。

结构：背景、问题、影响、约束、可能解决方案等部分。

如何统筹想法：写得好的问题陈述，让任何人（不论角色）都能理解问题本质和重要性，权衡偏好的解决方案。也留下对话永久记录，方便回头参考——问题越大，越可能重现或再议。

小贴士：别跳过最后一部分，就算想到的方案都不太好。任何工程师都能发现问题，架构师的职责是找解决方案。至少，提几个烂主意能为别人提好主意铺路。

事后总结

目的：防止灾难性问题重演。

受众：对近期宕机、故障、高优先级bug感兴趣的人。

何时撰写：技术问题造成异常影响时。多数bug不用事后总结，但如果严重干扰业务（比如值班开发者被呼叫、客户投诉），就该更进一步。

内容：无责描述表面问题及如何被发现。附相关对话、拉取请求、问题跟踪单链接。加受影响人、解决耗时、期间缓解措施细节。最后解释根本原因，建议预防再次发生的方法。

结构：背景、问题、影响、时间线、根本原因、建议流程变更等部分。

如何统筹想法：事后总结帮组织从“这绝不能再发生”的恐惧焦虑，转向“我们会确保”的信心安心。用对了，还能推动文化从个人追责转向组织能力和自动防护。