工程交流的十个优秀实践，你知道几个？

-- 背景 --

当你开始一家新公司并且必须非常快速地交付一个MVP以评估市场适应性时，你可以原谅自己的粗心。在那个阶段，目标是进行原始实验，以便迅速评估你正在创建的产品的可行性，并快速进行变更。在这个阶段，你通常是一个小团队，每个人都彼此了解并始终保持沟通。

(资料图)

但随着公司的发展，这种操作方式无法扩展，沟通变得越来越大的问题。以下是你可以使用的十个实践，以显著改善公司（或团队）的沟通。

-- 原理 --

这些戒律的总体目标是最小化上下文切换的成本，以便你的工程师可以更快地进入流程。这也意味着更快地提供更好的软件。

这些做法不仅有利于你的同事，而且在你回顾自己的旧工作时也有利于未来的你。

1.把同事当作客户对待

你最重要的客户是价值流中的下一步。如果你是一个与基础设施工程师紧密合作的开发人员，请确保你的工作与基础设施兼容（考虑12因素应用程序）。如果你是一名运维工程师，请确保开发人员可以自助获取资源并部署应用程序。

确保你持续获得同事的反馈，并根据需要调整以满足他们的需求并减轻他们的工作负担。

2.像准备要开源一样创建代码仓库

我曾在许多地方工作过，那里的代码仓库非常混乱，有多余的文件和代码，没有README文件，文件结构混乱，甚至还有密钥。每当你创建一个仓库时，请将其视为要开源，并考虑到那些不认识你或你的工作的人；他们如何知道这个仓库是关于什么的？

3.追求编码简洁性

有些工程师编写复杂的代码，因为他们觉得自己显得更聪明。我甚至遇到过一些认为代码行数越多意味着工作产出越多的人。

绝对不，绝对不是这样。编码就像写作一样，当写得清晰简洁时，会更优雅、更简单、更容易理解。我理解想要写更多代码行的想法；如果经理只看到五行代码，他们可能会觉得你懒惰。如果你在这样的公司工作，我建议收拾行李换工作。你需要在一个鼓励工程技艺的组织中工作；这对你的技能和心理健康最好。

编写简洁的代码需要更多的时间和精力。它还与设计紧密相连；如果你在键盘上猛击一堆代码，你很可能对整个过程并不十分了解，并最终交付一份令人困惑的杂乱无章的文档和自动化过程。

4.将Kondo原则应用于你的文件结构

Marie Kondo关于房屋整理的哲学很简单：只保留那些“激发喜悦”的东西，让一切整洁有序。

文件可能没有物品那么令人愉悦，但是你不应该保留任何不起作用的东西。工程师在代码仓库里摸索、尝试解决问题的各种不同方法，然后在成功后留下所有东西，这种情况太常见了。这种混乱使得后来找到该仓库并尝试理解其目的的人非常困惑。对于下一个需要清理你的混乱的人来说，这也更具挑战性，因为他们需要知道如何删除而不改变你的代码的功能。请记住，你可以在git中恢复删除的所有内容，所以在清理时要毫不留情！

文件结构同样至关重要。我曾与许多人合作，他们创建代码仓库的文件结构就像我母亲整理她的厨房一样——她知道每样东西都放在哪里，但其他人却不知道！一个有组织的文件结构和合适的目录名称使理解变得更容易。为需要解释的任何目录添加README.md文件。

5.了解你正在做的事情

这一点似乎很明显，但你不知道我遇到了多少次显而易见的是工程师不知道自己在做什么的代码。

我遇到的最恶劣的例子是开发人员编辑NGINX和Apache配置文件，试图解决他们的Java代码中的问题，而这些问题本应该在代码中解决。他们从StackOverflow粘贴配置行，看看是否有效；有时有效，有时没有任何作用，但他们总是把所有内容留在文件中。结果是，我继承了庞大的配置文件，没有人能理解，也没有人敢编辑，担心会破坏某些功能。

不要盲目地复制粘贴StackOverflow上的代码。尝试理解你粘贴的代码，并附上来源和解释的评论。ChatGPT和其他AI工具会使这个问题变得更糟；如果你使用这样的工具，试着让AI先解释一下，并添加相关的注释！

6.根据上下文进行文档记录，而不是全面记录

当敏捷宣言说“优先考虑有用的软件，而非详尽的文档”时，他们并不是说完全不需要文档。但这并不意味着你需要过度记录所有东西。

上下文文档旨在为了解、操作和诊断应用程序的人提供所需的所有信息。为什么、什么时候、谁、什么和怎么做；先决条件、示例、如何测试应用程序——任何你需要开始的东西。

想象一下，我给你一个包含50种不同类型的草药和厨房食材描述的清单——这就是详尽的文档。现在想象一下，我让你用这些东西做饭。如果没有任何先前的知识，你能做到吗？可能不能，但这就是大部分软件文档的现状（想想man页）。

相反，如果我给你一些解释如何使用这些草药的食谱会更有帮助——这就是上下文文档。提供上下文文档对用户更有价值，而且可能花费更少的时间。

如果你的上下文文档臃肿且难以理解，问问自己以下问题，我是否可以通过设计我的工作来减轻这种情况？答案通常是肯定的，因为令人困惑和过多的文档通常掩盖了糟糕的设计。

始终询问同事和其他团队你的文档是否合理，并在需要时改进。目标是他们不需要向你提问，他们可以自己有效地解决问题。

7.将文档与源代码保持紧密联系

如果索伦在指环上附上了一个很好的README.md文件，甘道夫可能会更早地了解到指环。

许多公司有一个趋势，所有文档都放在Confluence中；这是一个好做法。然而，这通常意味着将文档与代码库分开。我认为这种做法存在两个问题：

你需要维护两个真实来源。你必须相信你的客户知道这个Confluence页面在哪里，以及她是否有权限访问。

让所有内容都集中在一个地方，可以让你和你的客户更简单。我建议在Confluence中引用代码库，添加对其功能的描述，并提供指向README.md的链接以获取更多文档。

在wiki中维护适用于多个代码库的通用文档或具有复杂格式的教程，同时在需要时提供指向代码库中README.md文件的链接。这样，更新README.md文件的详细信息会更容易。

或者，你可以使用任何简化此过程的工具，让文档方便使用且集中存放，同时只需编辑一次。最重要的是，查看你的代码的人应该知道文档在哪里并能够访问它。

8.为同事编写有意义的工单

当你编写工单时，请提供简洁明了的细节。我经常看到这样的糟糕工单：

一句话、含糊不清的工单：比如“为x创建角色”或“为y提供根权限”并不是好的工单。

杂乱无章、冗余信息过多的工单：一个常见的例子是粘贴一系列电子邮件，这样需要完成工作的人必须阅读整个交流过程并试图理解其中的意义。这样做浪费了需要完成工作的人大量时间去建立上下文。

相反，你可以使用这样的结构：

描述：包括上下文和原因。验收标准：包括验收人。有用的来源：指向可能有助于完成任务的资源的链接。工作位置：指派人在需要时可以填写。

对于更新和障碍，请使用工单的评论。如果需要，每天都可以这样做。

这样编写工单非常有助于了解你的看板以及每个人正在从事的工作。这也使得查看工作流程和常见障碍更容易，避免了每天站立会议上信息未被记录且流程被中断的情况。

9.共享工程和沟通原则

仅凭你自己产出优秀的工作是不够的，如果你必须不断地修复他人的工作或试图理解他们的混乱，有时候最好退一步，与团队成员或其他与代码有关的团队进行讨论，并尽早解决这些问题。

明确并有效地定义什么是优秀的工作以及如何实现它，制定一些指导方针并与你的团队和整个公司分享——最重要的是，承诺遵循这些指导方针！

10.将大部分努力用于创新和优雅的设计

确保花时间做好工作；如果产品负责人或其他人试图推动你更快地交付，请寻求折衷，并解释现在节省时间，将来会花费更多时间和金钱。敏捷并不意味着高速开发；它意味着快速、短小的高质量软件迭代，遵循节省时间的设计原则。

-- 总结 --

最近，我对平台工程和内部开发者平台的实施变得非常热衷，因为通过将工作哲学转向自助服务和开发者体验（DX），上述所有原则都成为开发的基本目标。然而，了解良好沟通的原则以及如何实施它们是了解为什么它们可以长期节省时间和精力的基本要求。

-- 补充 --

以下五点补充建议将有助于提高团队在工程交流方面的效率和协作，从而提高项目的成功率。

11.定期进行代码审查和团队讨论

通过定期进行代码审查和团队讨论，可以确保团队成员共享知识、了解彼此的工作以及相互学习。这有助于减少误解，并在项目中建立统一的编码和文档风格。

12.使用可视化工具来解释复杂概念

利用流程图、架构图和其他可视化工具来解释复杂的系统和概念。这将有助于提高团队对项目的理解，并使概念更容易传达给新成员或其他团队。

13.提倡开放式沟通和反馈文化

鼓励团队成员在遇到问题或不清楚某些事物时，主动寻求帮助和建议。通过建立一种积极的反馈文化，可以确保问题得到解决，并鼓励团队成员互相学习。

14.定期进行知识分享会

组织定期的知识分享会，让团队成员分享他们在项目中学到的新知识、技术和最佳实践。这不仅可以提高团队的技能水平，还有助于建立团队凝聚力。

15.利用协作工具进行有效沟通

使用协作工具，如Slack、Microsoft Teams或其他即时通讯工具，以便团队成员可以轻松地共享信息、讨论问题并协作解决问题。同时，利用项目管理工具（如Jira或Trello）跟踪任务和进度，确保团队工作得当且透明。

关键词：