黄金路径是什么：如何解决软件生态系统碎片化问题

“香料带来的幻象向他展示了无数个人类走向灭绝的未来也展示了人类得以幸存的唯一未来。他将这个未来命名为‘黄金之路’并决心让它成为现实。”以上引文来自海外某百科社区对弗兰克·赫伯特 1976 年科幻小说《沙丘之子》的简介。这段话非常贴切以至于我几乎可以确定海外某音频科技公司的团队中至少有一位成员在提出“黄金路径”这个概念时读过《沙丘》系列的第三部。好了回到现实。六年前这家海外音频科技公司一直致力于打造敏捷工程文化并采用高度自主的小团队模式。这种模式带来了许多优势但也带来了一些复杂性。其中一个典型问题就是开发者工具生态系统逐渐碎片化。工程师如果想知道某件事该怎么做常常只能去问同事。我们开玩笑地把这种模式称为“谣言驱动开发”。这种方式也许在初创公司甚至大型初创公司中还能运转。但随着公司不断发展我们逐渐意识到这种软件开发方式正在拖慢我们的速度。我们发现依赖“谣言驱动开发”的模式根本无法规模化。简单来说黄金路径就是一条经过明确指导、受到平台团队支持的标准构建路径。它的价值不在于限制工程师而在于减少重复决策、降低工具碎片化让团队更快、更稳定地交付软件。很明显作为组织的基础设施部门也就是下文所说的“平台团队”我们需要推动开发者工具之间更好地协同。但我们要做的不只是这些。被推荐或认可的工具应该易于发现使用流程应该清晰明了还应该配套高质量的使用指南。此外如果用户遇到问题也应该能够轻松找到支持渠道。什么是黄金路径第一条“黄金路径”和第一份“黄金路径教程”是在六年前为后端工程开发的。和这家公司许多创新一样最初的后端工程黄金路径教程也是一个内部创新周项目。下面这段摘自平台团队的一篇内部博客文章我们的目标是让开发者在公司内部工作和构建产品时拥有极佳体验。我们面临的一大挑战是如何统一各种使用基础设施的方式并提供能够满足众多团队不同需求的工具。……在内部创新周期间八位优秀工程师共同完成了一份关于如何使用我们服务的教程并将其命名为“黄金路径”。我们希望通过这种方式帮助用户轻松、高效地完成工作。当然如果你喜欢冒险也可以偏离黄金路径另辟蹊径但那样就无法获得同等程度的支持。在这里工作应该轻松顺畅而这份教程正是为了实现这一点为用户提供有价值的资源。作为负责技术文档和产品发现能力的产品经理我一直对“黄金路径”这个概念深感着迷也持续关注它所解决的问题。上面这段话的大部分内容即使放到今天来看也几乎像是昨天才写下的。黄金路径如何解决软件生态系统碎片化曾经这家公司的工程师无法想象什么是黄金路径如今我们已经无法想象没有黄金路径的工作方式。多年来后端工程黄金路径教程持续演进。我们又陆续为客户端开发、数据工程、数据科学、机器学习和 Web 开发等领域新增了黄金路径。事实上最近音频处理也加入了这一体系。按照我们今天的定义“黄金路径”是指一条“有明确指导、并获得支持的构建路径”。例如构建一个后端服务、搭建一个网站或者创建一条数据管道。黄金路径教程则是一份循序渐进的教程它会引导你完成这条受到指导和支持的路径。那些被“精选”的工具也就是位于黄金路径上的工具会以可视化方式呈现在我们的内部开发者门户的“探索”版块中。用户可以按领域进行筛选。黄金路径基础设施和工具。而使用这些工具的路径则体现在黄金路径教程中。这些教程使用“文档即代码”的技术文档工具创建并同样呈现在内部开发者门户中。后端黄金路径示例。设立黄金路径并不是为了限制或扼杀工程师的创造力也不是为了制定标准而制定标准。有了黄金路径团队不必重复造轮子需要做出的决策也更少。这样他们就可以把生产力和创造力投入到更高价值的目标上并重新快速行动起来。如果企业希望把“黄金路径”进一步落到研发流程中也需要有工具承载目标、需求、开发、测试、发布和知识沉淀等关键环节。例如PingCode这类智能化研发管理工具可以将团队目标、客户反馈、需求评审、项目开发、测试发布和 Wiki 知识沉淀连接起来让推荐路径不只是文档里的最佳实践而是能够在研发全生命周期中持续流转的数据和流程。有趣的是“黄金路径”这个概念已经变得非常流行并深深融入了我们的工作方式以至于后来又衍生出“铺装路径”“白银路径”等概念。我们的目标是尽可能引导所有人走上黄金路径。黄金路径教程成功的关键因素如前所述黄金路径教程的主要任务是引导新入职工程师逐步掌握其所在工程领域的黄金路径。多年来大多数用户反馈都表明这些教程在这方面非常成功。黄金路径教程已经逐渐被视为公司最重要的技术文档之一。以下是黄金路径教程取得成功的几个关键因素。明确的受众我们在编写教程时会明确目标受众新入职工程师。这让我们能够对读者已有的知识水平做出合理假设也能帮助我们决定应该以什么方式进行讲解。其他经验丰富的工程师同样会阅读这些教程。例如转向新领域的工程师或者想了解当前最佳实践而不是五年前做法的工程师。但最重要的是我们始终以新工程师为主要目标受众来编写教程。这样做可以确保所有用户都能理解其中的说明。一个主要目的理解并清楚传达教程的目的至关重要。我们曾经犯过的一个错误就是没有把这一点说清楚。工程师们包括我和我的团队都开始追问这些教程到底是什么是操作指南吗是最佳实践展示吗是教育材料吗是参考资料吗还是以上所有内容的混合体这个问题一度让我非常纠结。起初我给出的定义是“这些教程面向新员工展示我们公司的工作方式。”这本来是我最喜欢的描述但不知为什么总觉得还差一点其他人似乎也没有真正理解。直到最近我偶然看到另一位产品经理对黄金路径和教程的描述。大意是“黄金路径是一条有明确指导和支持的系统构建路径而黄金路径教程则会引导你完成这条路径。”就是这个。我把这句话分享给其他人大家都非常认同。这正是我们一直需要的表述。我们终于找到了主要目的。一步一步来黄金路径教程是一份循序渐进的指南。我们努力包含每一个步骤例如点击哪里、按下哪个键等等。这种写法对作者来说可能有些繁琐对读者来说也可能显得冗长。但如果不这样做就很容易遗漏步骤。仔细想想遗漏步骤反而更容易造成困惑。此外循序渐进的写法也会让你更清楚地看到自己的黄金路径到底有多长。忠于黄金路径我们经常收到的一个反馈是教程太长了。我不是那种喜欢争辩的人但我的回答始终一致教程只是反映了真实的黄金路径。真正需要精简的是黄金路径本身。换句话说作为平台组织我们需要让实际的黄金路径更容易理解、步骤更少。这样一来教程自然也会变短。关键在于黄金路径教程必须反映实际的黄金路径。当一个工具被另一个工具替换时例如当我们采用新的容器编排技术时黄金路径教程也应该同步更新。每个领域一条路径如前所述我们为每个工程领域都设计了一条黄金路径教程。当然这并不是唯一可行的方式。例如我也可以想象一种更模块化的方法为每项工程任务设计一份黄金路径教程。或者换一个角度为测试、编码等主题分别创建教程。我们曾认真思考过这些方案但最终还是坚持了按工程领域划分的方法。即使现在 T 型工程师的趋势越来越明显我们仍然认为这种方式更适合当前场景。这关乎教育如果我们通过巧妙的工程技术大幅简化黄金路径比如只需点击三次就能搭建一个网站那么黄金路径教程是否会变成三段或者干脆就不再需要教程了这是一个很有意思的问题我也思考过很多次。坦白说大多数时候都是我自己在思考。我们的目标是帮助公司更快地发展。因此对于平台团队来说简化和缩短黄金路径帮助个人贡献者更快完成工作当然是合理的。但这样做也意味着我们会把很多东西隐藏在表面之下。系统中会出现许多“黑箱”。而黄金路径教程本身也具有教育意义。所以没错我们需要让工程师更容易地构建产品。但同样重要的是要记住教程的目的之一是教育尤其是教育新员工。特殊地位黄金路径教程是新工程师入职流程中不可或缺的一部分。它们作为新工程师的首要任务之一获得了非常积极的反馈并已被证明是帮助新人快速上手的有效方式。数据显示黄金路径教程是公司内部阅读量和使用率最高的技术文档之一。因此在我看来它们具有特殊地位。我们也努力将这一点传达给负责撰写和维护这些文档的团队。我们会告诉这些团队如果你负责黄金路径教程中的一部分而你能投入文档工作的时间非常有限那就优先把时间花在这里。反馈和测试如前所述黄金路径教程是我们新员工入职流程的重要组成部分。我们鼓励新工程师在入职后的前两周内完成与其主要专业领域对应的教程。之后他们会参加为期一周的“工程训练营”与其他工程师一起基于这套教程构建一个完整的端到端产品。因此几乎所有加入公司的工程师都会接触到黄金路径教程。这也是教程成功的关键因素之一大量人员会阅读、测试并反馈这些教程。当然这些反馈不仅针对教程本身也针对黄金路径本身。而对于平台团队来说这些反馈非常宝贵。黄金路径的未来发展我非常喜欢我们的黄金路径理念和黄金路径教程也为我们已经取得的成果感到自豪。但与此同时我也看到了许多创新和改进空间。下面列出三个方向。前两个方向我们正在积极推进第三个方向则还需要更长时间才能实现。改进所有权模式过去我们为每份教程都配备一名技术文档撰写人员。但这种模式无法有效扩展而且我们也因此忽略了公司整体技术文档中的其他一些问题。于是我们放弃了技术文档撰写人员一一对应的模式转而采用更集中化的方式来解决这些更广泛的问题。结果如何呢我们又制造了一个次级问题。由于每份教程都覆盖某个特定工程领域的黄金路径我们需要把内容所有权分散到许多团队中。这本身并没有问题。但这样一来我们失去了教程层面的协调能力——这原本由技术文档撰写人员负责也失去了教程集合层面的协调能力——这原本由所有技术文档撰写人员共同承担。我们并不打算回到旧模式但我们正在寻找解决这些协调问题的方法。黄金状态最近我们一直在探索“黄金状态”这个概念。所谓黄金状态是一系列检查项。工程师可以利用这些检查项判断自己的系统是否遵循了黄金路径。黄金状态的最终目标是让工程组织中的大多数成员都走上黄金路径。这样一来我们就能减少技术生态系统中的碎片化程度帮助团队降低维护成本。此外使用相同产品的人越多我们就越有可能实现自动化升级。而这正是团队真正需要的。面向端到端产品的黄金路径教程目前的教程设置主要面向个人贡献者。但个人贡献者通常身处团队之中而团队负责构建产品包括功能开发、实验运行、公司项目等。团队成员也往往来自不同工程领域。这无疑是一项挑战但我们对创建一系列面向团队的黄金路径教程感到非常兴奋。这些教程将为构建不同类型的产品提供蓝图。对于更偏通用协作的团队也可以借助 Worktile这类项目协作系统把任务、项目、文档、目标、日历、甘特图、工时和审批等信息统一承载起来让端到端产品路径更容易被团队理解、执行和复盘。这或许还需要很长时间才能实现。不过嘿——“香料带来的幻象向他展示了无数个人类走向灭绝的未来也展示了人类得以幸存的唯一未来。他将这个未来命名为‘黄金之路’并决心让它成为现实。”