原文链接：https://stackoverflow.blog/2025/08/20/documents-the-architect-s-programming-language/
资深开发人员知道如何将代码部署到由代码组成的系统中。
架构师知道如何将想法部署到由人组成的系统中。
从初级开发人员到高级/首席开发人员，职业道路通常很直接。您在编码以及使您能够更有效地编码的技术和非技术技能方面做得越好，您晋升的速度就越快。但是，一旦你达到高级水平，就会出现一个主要的分叉路口。
许多开发者会选择管理路线。这是扩大你的影响力并晋升的好方法。但一个缺点是，你不可避免地会减少编程时间——许多工程经理根本没有时间编写代码——如果你像我一样，这会让你无法接受。你过去埋头苦干，将棘手的流程转化为优美的抽象概念的时间，将会被开会、为你的团队排除障碍、调解分歧以及为人力资源部门勾选方框所占据。这是一项具有挑战性且重要的工作，但它非常不同。
另一个常见的选择是架构师路线。这让你能够继续深入代码，同时扩大你的影响并利用你的资历。在许多公司，架构师路线与管理路线具有相似的薪酬和职位晋升机会，并且两者都可以通往 C 级职位（如 CTO）。
但相比之下，架构师路线可能显得定义不清。当你转入人员管理时，你的日常工作会发生彻底改变。你的日程安排会改变，你的团队结构会改变——你的工作产出以完全不同的方式衡量。但成为一名架构师看起来很像成为一名高级开发人员：在 IDE 中编写代码、审查 pull request、讨论诸如部署管道和数据结构之类的事情。那么是什么让架构师与众不同呢？或者换句话说，如果你想证明你已准备好担任架构师角色，你该怎么做？
什么是架构师
为了澄清：我不仅仅是指架构师善于沟通或与他人合作良好，尽管这两者都很重要。这也不是我用华丽的辞藻来说明软技能的重要性，尽管它们确实重要。我的意思是，架构师知道组织和部署想法的有效、可重复的流程，超越了组织和部署机器和应用程序的流程。他们知道通过代码推送所能实现的目标是有限的；最重要的问题需要来自具有不同观点和职位的人的投入、协作和共识。
换句话说，大多数公司的多数工程师，如果没有其他开发人员和领导者的支持，就无法启动一个为期数月的项目、重写一个 Web 服务或为新产品选择编程语言。软件生命周期中最大的瓶颈与代码无关。它们是人的问题：沟通、说服、决策。
因此，为了产生影响，架构师必须持续地推动这些事情发生，一个迭代接着一个迭代，一个季度接着一个季度。如何可靠地让正确的人在正确的时间、正确的地点，讨论正确的事情？是否存在一种适用于人类的传输协议或基础设施即代码工具？
优秀文档的原则
- 记录事情，而不是担心如何构建它们
- 文档文化，而不是为了检查而检查的行为
- 思考什么才是相关的，而不是使用模板
- 时间点文档，而不是持续更新
请记住第一点和第三点：最好写下你知道的内容，而不是陷入寻找正确格式的困境。而且格式甚至不需要在不同的文档之间保持一致。专注于对你现在呈现的信息有效的方法，而不是以前有效的方法。
如何编写文档
即使您没有太多的技术写作经验，您仍然可以编写出色的文档。有一个简单但非常有效的技巧可以改进您编写的几乎任何文档：项目符号。
项目符号非常神奇。它们能让您专注于完整性和结构，而不是句子流畅性和风格。阅读技术文档的人试图快速找到信息——事实上，衡量文档质量的最佳指标之一是人们停止阅读文档的速度。如果他们能在十秒钟内找到他们需要的东西并离开，那就是胜利。而且由于项目符号往往信息密集且易于浏览，因此它们是完成这项工作的完美工具。
以下是将最后两段转换为项目符号的形式：
- 帮助您专注于完整性和结构
- 不需要太多的写作技巧
- 使文档更易于浏览
这几乎包含了 100% 相同的信息，但只占用了 25% 的页面空间。而且写起来也更容易。这就是为什么项目符号是架构师最好的朋友。
你可以使用的第二种最有价值的技术是标题。除非你的信息可以用非常少的项目符号来表达，否则值得将其分解为具有有意义标题的章节。
例如，我写的大多数文档都以“背景”部分开头。其目的是提供关于主题的历史、业务领域或预先确定的约束的信息和链接。你可能已经掌握了所有这些信息，因为你每天都在积极地处理它，但其他读者会感谢你的记忆提示。一年后，当你回顾自己的文档时，你也会感谢它。
当然，对当前主题已经有深入了解的人可以浏览或跳过“背景”部分。这就是标题的妙处：它们使人们更容易找到他们正在寻找的任何信息，而忽略他们不需要的信息。（如果你有超过几个标题，并且想要进一步优化，那么添加一个链接的目录是一个很好的选择。）
如果你一开始不知道该使用哪些标题，只需按脑海中出现的任何顺序写下要点。然后将它们组织成逻辑组并进行标记。这与编程并没有太大区别：你可能会先写一个 200 行的方法作为初稿，但一旦它开始工作，你通常会通过将其分解为多个步骤并将常见模式提取到函数中来进行重构。
你最应该避免的是冗长的文字。你的文档最需要关注的人往往是时间最紧张的人。如果你给他们发一篇四页纸的文章，他们很可能永远没有时间读完。而组织良好的项目要点，则能让他们轻松浏览，收集所需信息，并在有空的时候做出回应。
如何处理您的文档
当你把所有必要的信息都记录下来之后，可以考虑进行一次完整性检查。将它发送给你密切合作的人，请他们指出任何看起来错误或不合理的地方。然后根据他们的反馈进行澄清、重组或改写。
请记住，大多数文档更像是临时性的 Bash 脚本，而不是持续运行的 SaaS 应用程序。一旦文档完成了它的工作，您可能永远不会再更新它。作为一名架构师，您一年可以轻松编写一百份文档；您肯定没有时间维护所有这些文档。
这有两层含义。首先，你应该确保每份文档都足够好，以便日后有用，即使它逐渐过时。现在多花一些精力是值得的，这样你就可以忘记它，直到它再次出现。其次，你应该让人们很容易判断文档最初编写的时间，反之亦然，很容易找到在同一时间段编写的文档。当时间点文档的过时程度显而易见时，它会更有用。
我的方法可能看起来有些反直觉。大多数人一开始会按照主题来组织文档：一个文件夹用于此功能，另一个文件夹用于彼功能。但这会导致出现一堆表面上相同但价值并不完全相等的文件夹。其中一些文件夹充满了最新的、高度相关的文档；另一些文件夹则没有任何过去五年的文档；还有一些文件夹混合了新旧文档，其中一些文档直接相互矛盾，并且无法立即清楚它们应该按什么顺序排列。
因此，我几乎将所有文档按时间顺序组织：按年份，然后按迭代。这有助于保持时间线的可见性。例如，在 Confluence 中，我为每个团队或产品创建一个“空间”（其他工具可能称之为“工作区”、“wiki”或“书”），一些高级别的逻辑分离是有用的，但在每个空间内，文件夹结构看起来像这样：
- 📄 概述
- 📄 架构
- 📁 2025
- 📁 Jan 1 Sprint
- 📄 提案：SSO 登录
- 📄 APP-132 用户会话研究
- 📁 Jan 15 Sprint
- 📄 APP-135 允许为配置的客户端进行 SSO 登录
- 📁 Feb 2 Sprint
- 📄 SSO 登录和用户角色问题
- 📄 开发预测：角色权限复杂度不断升级
- 📁 Jan 1 Sprint
请注意，对于少数高级文档来说，持续维护是有意义的。如果有人对产品总体上感兴趣，那么拥有一个最新的着陆页，也许还有一个架构图是很好的。但是大多数文档都有一个保质期：随着时间的推移，它们的相关性会越来越低。
附录：具有高影响力的文档类型
架构概览
目的：帮助他人快速了解系统的结构和设计。
受众：系统中的所有利益相关者：经理、开发人员、运维工程师、产品负责人等。
何时编写：在构建新系统或重构现有系统之前。当任何现有系统难以理解时也很有用。
描述一个系统的主要组成部分（数据库、应用程序、云服务、负载均衡器等）以及它们之间如何通信。也可以描述内部组件，如数据模型和类，但应避免过多的细节。
结构：可以是一个包含圆柱体、方框和箭头等符号的图表，一个包含章节和子章节的多页文档，或者仅仅是一个嵌套的要点列表。常见的格式包括 arc42 和 C4。
开发设计
这听起来是假的，但这是真的：您编写的文档越多，您需要编写的代码就越少。文档可以帮助您避免因误解、不正确的假设和设计错误而导致的 PR 反复和重写。它还可以帮助您避免将大量时间投入到不会有任何结果的探索性编码中。
目的：获取关于您计划编写的代码的反馈；帮助您在编写大量最终会被丢弃的不成熟代码之前，发现未知因素和复杂性。
受众：您团队中的其他开发人员；希望了解系统演变的未来开发人员。
何时编写：在您开始处理任何重要的编码任务之前。也可以在您开始处理看似微不足道但结果变得更加复杂的事情之后编写。
细节的程度取决于您。不要详细说明任何显而易见或平淡无奇的事情，但要包含足够的信息，以便其他开发人员可以指出不正确的假设，并推荐您可能没有意识到的现有逻辑/模式。
结构：将要遵循的步骤列表。例如，修改 A 类，添加一个执行 X 的方法；创建 B 类，包含关于 Y 的数据；创建一个执行 Z 的数据库迁移，等等。您还可以包含一个“未决问题”部分，列出开始之前需要解决的任何问题，或者一个“替代方案”部分，列出您希望团队成员权衡的不同实现方式。
如何协调想法：开发设计帮助开发者分享知识，并保留系统的核心模式和抽象。它们还创建了一个永久记录，记录系统是如何变成现在的样子的。如果您的团队不进行结对/群组编程，开发设计可以为您提供许多相同的好处，同时还可以帮助未来的贡献者学习系统。
项目建议书
为了让你的提议更容易被接受，请确保技术和非技术利益相关者都能理解。记住，其他人不会一直想着你在做什么，所以你需要比你想象的更多的背景信息。事先考虑做一些研究，无论是数据挖掘来确定有多少用户会受到影响，四处询问以了解问题的严重程度，还是阅读其他团队和公司如何处理类似的项目。
目的：为了沟通项目的价值和成本，以便分配时间和资金。
受众：领导者和产品负责人。
何时编写：当计划会议即将到来时，或者当您看到有机会有意义地改进或扩展公司的产品和系统时。
总结了领导者评估一个项目相对于另一个项目的优先级所需了解的一切。为什么它很重要？它会影响谁？需要多长时间？等等。
结构：几个清晰标记的部分，如背景、待解决的问题、建议的解决方案、用户影响和预计的工程工作量。
它如何协调想法：项目提案是大型、有影响力的、耗时数月的项目诞生的方式。它们为整个团队设定了路线图。
开发者预测
保持中立的语气，这样您听起来不像一个末日预言家。考虑多种可能性，不要试图让整艘船掉头；只需指出冰山并提出处理方法。
目的：提出比预期更糟的结果的可能性，特别是那些你的经验让你有独特资格预见的结果，然后提出应对这些结果的方法。
受众：业务决策的利益相关者。
何时编写：当您作为工程师，感觉某项决策有风险或可能令人失望时。
内容：首先总结做出该决策的原因以及决策者希望实现的目标。解释导致您认为可能出现负面结果的因素。描述这些结果是什么。然后提出减轻这些结果的方法，即使最终决策没有改变。
它如何协调想法：开发者预测可以帮助您分享您的专业远见，并让人们思考计划中的缺陷。它还可以让组织做好准备，在出现问题时快速而熟练地应对，而不是反复掩盖问题。当计划开始失败时，您的预测可以成为某种北极星，展示期望与结果之间日益增长的对比。
技术菜单
尽量避免推崇你的个人偏好。如果你是编写菜单的人，请与使用不同技术的开发人员进行几轮反馈。给予他们的意见与你自己的意见同等重要的权重；让团队达成共识比选择绝对“最佳”技术更重要。
目的：减少启动新应用程序时的决策时间。
受众：开发团队或组织。
何时编写：当您计划一个项目并且对使用哪些技术存在不同意见时。
内容：对于给定的技术类型（编程语言、运行时、框架、平台等），重点关注您和您的同事最喜欢的选项。比较每个选项的优势：您的组织对其熟悉程度如何（不仅是使用它进行构建，还包括部署和维护）？是否容易招聘到了解并喜欢它的开发人员？它是否拥有健康的开源生态系统和良好的文档？普通开发人员使用它从零开始到开发出有用的应用程序需要多长时间？它是否鼓励在代码库中可识别的标准、结构和模式？它在需要时是否具有高性能？一旦您对技术和非技术方面的优缺点有了全面的了解，就可以为何时使用每种技术提出建议。一种可能是您的 Web 服务的默认选择，另一种可能是无服务器函数，还有一种可能是原型和内部应用程序。
结构：一个对比图表，然后针对几种不同情况提出明确的建议。
它如何协调想法：技术菜单有助于就事物的构建方式达成共识，使开发人员能够启动有用的技术，而不会陷入“这个与那个”的争论中。它还可以挑战那些仅仅依靠传统而非适用性或受欢迎程度而幸存下来的公司默认设置。
问题陈述
不要跳过最后一部分，即使想到的解决方案似乎都不是特别好。任何工程师都可以发现问题，但架构师的工作是找到解决方案。如果没有别的，提出一些坏主意可以为某人提出一个好主意铺平道路。
目的：快速达成关于如何解决或规避问题的共识。
受众：项目的利益相关者。
何时编写：当您遇到没有明显解决方案的问题，并且需要组织对此做出明确决策时。
用简单的术语解释问题的本质。如果它有明显的业务影响，请描述（或估计）范围和严重性。大多数问题都涉及两个或多个无法同时满足的约束；如果是这种情况，请明确说明这些约束是什么以及它们为何相互矛盾。然后提出几种可能的解决方案，总结每种方案的优缺点。
结构：诸如背景、问题、影响、约束和可能的解决方案等部分。
它如何协调想法：一个写得很好的问题陈述，可以让任何人，无论其角色如何，都能理解问题的本质以及它为什么重要，然后权衡他们偏好的解决方案。它还会留下对话的永久记录，以便您可以参考它——问题越大，它越有可能重新出现或在以后被重新讨论。
事后分析
事后分析是承担错误责任的机会，但不是自我鞭笞的练习。每个人都有糟糕的日子并且会犯错误。组织的目的在于创造超越任何个人所能提供的韧性。承认你所扮演的角色，但始终关注整个组织可以做得更好的方面。
目的：防止灾难性问题再次发生。
受众：对最近的中断、故障或高优先级错误感兴趣的任何人。
何时编写：当技术问题产生异常影响时。大多数错误不需要事后分析，但如果业务流程受到重大干扰（例如，值班开发人员收到呼叫或客户打电话投诉），那么可能需要更进一步。
以不带指责的方式描述明显的问题以及您如何注意到该问题。包括指向任何相关对话、拉取请求和问题跟踪单的链接。添加有关受影响者、问题解决所需时间以及在此期间为缓解问题所做尝试的详细信息。最后，解释问题的根本原因，然后建议防止问题再次发生的方法。
结构：诸如背景、问题、影响、时间线、根本原因和建议的流程变更等部分。
它如何协调想法：事后分析帮助组织从“这种事情绝不能再次发生”的恐惧和焦虑转变为“我们会确保这一点”的信心和安全感。如果使用得当，它们还有助于将文化从个人指责转变为组织能力和自动保障。
AI总结（人工审核，TLDR）
文章核心思想
这篇文章探讨了从高级开发人员晋升为软件架构师的职业道路。作者认为，架构师与高级开发人员的根本区别不在于编码能力，而在于通过高效的文档来组织和驱动人员、流程和决策，从而扩大其影响力。软件开发中最大的瓶颈往往是“人的问题”（如沟通、说服、达成共识），而结构化的文档是解决这些问题的核心工具。
主要论点摘要
- 架构师的角色定义
- 在高级开发人员之后，职业道路分为管理路线（减少编码，专注人事）和架构师路线（贴近技术，扩大影响）。
- 架构师的工作看似与高级开发人员相似（编码、代码审查），但其核心职责是解决“人的问题”，推动跨团队的协作和决策。
- 文档是架构师的关键技能
- 原则：
- 先记录，再求格式：不要因为追求完美的模板而拖延。
- 建立文档文化：让文档成为习惯，而不是为了应付检查。
- 关注相关性：内容比固定的模板更重要。
- 视为“时间点”快照：大多数文档完成其使命后便可存档，无需持续更新。
- 写作技巧：
- 多用项目符号（Bullet Points）：它们信息密度高、易于浏览，能帮助作者专注于结构和完整性，是架构师最好的朋友。
- 善用标题（Headings）：将文档分解为逻辑清晰的部分（如“背景”），帮助读者快速定位信息。
- 组织方法：
- 按时间顺序组织：作者强烈建议按“年/迭代”来组织文档，而不是按“功能/主题”。这能清晰地反映决策的时间线，并有效处理文档过时的问题。少数核心文档（如架构总览）可以保持常青。
- 原则：
七种高影响力的文档类型
文章附录详细介绍了七种关键文档，它们是架构师协调想法、推动项目的有力工具：
- 架构概览 (Architecture Overview): 帮助所有利益相关者快速理解系统结构。
- 开发设计 (Development Design): 在编码前获取反馈，减少返工。作者强调：“你写的文档越多，需要写的（废弃）代码就越少。”
- 项目建议书 (Project Proposal): 向领导层阐明项目的价值与成本，以争取资源。
- 开发者预测 (Developer Forecast): 以中立的口吻提出潜在风险和负面结果，帮助组织提前准备。
- 技术菜单 (Technical Menu): 为团队预设推荐的技术选项，减少决策时间和争论。
- 问题陈述 (Problem Statement): 清晰地定义一个复杂问题及其约束，并提出多种解决方案，以快速达成共识。
- 事后分析 (Postmortem): 在故障发生后，以非指责的方式分析根本原因，并提出改进流程，防止问题重演。