别再让你的其他非技术团队成员觉得你很不友好了。
想象一下这种情况：你是一名软件工程师，正在尝试debug某个问题。销售、客户服务或其他部门都在询问最新状态，因为有一些愤怒的客户正在责骂那位可怜的代表，而他只是在等待一个合理的解释。
你并不喜欢这种压力，你只是想回到工作中，这样你就可以完成任务，然后去喝一杯啤酒。这个问题涉及很多方面，许多齿轮在不同方向旋转，毕竟，你正在处理的系统非常复杂，需要你全神贯注，这样你才能修复它，同时保持其余功能不受影响。
而你最不想做的事情就是分心在 Slack 或 Jira 上写一份愚蠢的报告。
如果这听起来似曾相识，我深有同感。我们的工作就是修复和维护几乎无人能懂的复杂系统。不仅如此，我们还必须把这些难题用简单的语言翻译给那些对软件工程毫不关心的人。
我写这篇文章的目的就是帮助你把这些工程问题，转化为一个对技术毫无兴趣的 12 岁孩子也能理解的东西。这样，你就能有效地沟通你正在做的事情，经理、PM、设计师和其他人也能清楚地知道问题所在，最终不再打扰你。
以下是一份步骤清单，可以帮助你以清晰、有效的方式撰写状态更新、根本原因分析或任何技术解释，让你看起来像一个真正的专家，为非技术人员提供参考。
1. 按照你的理解准确地写下来
你不需要把它写得很漂亮，它需要尽可能的原始。你只需要以一种对你有意义的方式完成它。
重要的是，你要写出问题的来龙去脉，不要遗漏任何环节。就像你在和过去的自己说话一样，把它解释清楚，因为过去的自己还没有意识到即将到来的麻烦。
写下来有两大好处：
- 通过简单的书写，你可以将不同的问题归类。这很有用，因为在头脑中处理所有这些想法可能会非常困难。把它写在纸上，你就把记住所有东西的任务交给了其他事情，从而解放了你的头脑，让你可以去完成其他任务。
- 有了草稿，你现在就有材料开始进行真正的技术解释了。
2. 接受一个事实：你刚刚写的东西可能是垃圾
别误会，这对你很有用。而且可能非常有意义。
但它只对你有意义。而且我们也不知道这种意义会持续多久。两周后，那段文字对你来说可能会和对一个语言不通的人一样令人困惑。
但请记住，这不是关于你自己。这是关于其他有着完全不同的世界观、背景、专业领域和兴趣的人。他们没有时间去学习计算机科学课程，只是为了弄明白你刚才想说什么。
想象一下Neil Degrasse Tyson、Mark Rober或你能想到的任何科学内容创作者。你觉得他们在尝试每一个想法时，都要重做多少次脚本、验证多少次假设、多少次重新开始？
答案：非常多次。
谦卑的教训： 如果他们每次创作内容都要进行多轮这样的工作，你认为你能在不重新阅读一次的情况下清晰地向一个没有工程背景的人传达一个复杂的问题吗？
3. 删除所有可能类似伪代码的条件、程序、想法。将其转化为业务术语
如果你用程序术语来表达，即使是工程师也无法理解你的意思。他们最好还是自己阅读代码。因此，请尽量避免这样做。
以下是几个从我所喜爱的“技术宅”语言到实际表达时英语的例子，希望这些例子能给你一些提示，如何提高表达清晰度。
示例 1
技术宅：在 API Gateway 发布消息之前，控制器需要验证查询参数。DTO 验证抛出 400 错误，因为该数字在枚举中不存在。
英语：系统出错了，因为用户发送了一个无效的状态。
示例2
技术宅：由于组件在依赖数组中缺少一个变量，因此 React 无法在 useEffect 中正确分派用户数据。
英语：我们的系统存在一个bug，点击login按钮后针对这个特定case，我们没有正确存储用户数据。
示例3
技术宅：查询builder返回一个具有超过 10 个连接的查询，在将所有这些数据传递给用户服务后，服务器抛出堆分配错误。
英语：我们需要优化从数据库获取数据的方式，以避免服务器内存耗尽。
4. 没有人拥有你所拥有的技术背景。永远不要认为某件事显而易见，因为事实并非如此。
出现错误是因为 SQL 中没有存储某些内容吗？外键约束？竞争条件？是只发生在分布式键值存储中的数据完整性/缓存问题么？
对于非技术人员来说，这些词中有几个真正有意义？
如果愤怒的顾客是一位 80 岁的老奶奶，那么这些话在她听来毫无意义。把这个刻板印象作为你的目标：她不懂技术，也不关心技术。然而，她必须知道为什么她没有收到她付款的东西。。
因此，首先从业务规则的角度解释为什么这很重要，并删除那些不是绝对需要的技术术语。
场景演练
假设你在一个音乐会和文化活动的票务应用程序中工作。公司最近推出了一项功能，即一个账户可以为一群人购买多张门票，并享受折扣价。购买完成后，该团体的每个成员都会获得一张 PDF 格式的个人门票，前提是他们都是该应用程序的活跃会员。
发布后不久，就报告了一个问题：只有购买了所有门票的人才能获得一张门票的 PDF，其他成员即使付款成功，也不会收到任何东西。
在这个假设的场景中，你发现了问题所在。在编写第一条 Slack 消息时，你最终得到了如下内容：
- 竞争条件导致外键约束失败。因为在PDF Worker抓取队列中的createTicketForGroup任务时，票务服务尚未生成account_group_ticket行，S3文件上传失败。
这些话有没有任何意义？也许有，也许没有（毕竟这是一个虚构的场景）。不过，让我们将其转化为高层次的实际情况：
- 我们的系统需要识别与该组相关的所有人员才能创建门票，以避免出现分配两次座位等各种问题。由于所有成员在门票生成过程开始时同时被分配到一个新组，因此有时后者会先完成。这种情况只会在组服务过载且票务服务可用的计算资源较少时发生。
在这种情况下，系统无法检索到创建票证所需的信息，并在尝试保存包含票证数据的PDF时出现错误。这就是为什么客户无法看到音乐会门票，即使系统最终生成了条目。
解决这个问题需要......（这将持续一段时间）
列举一下主要的变化：
- 解释了架构中两个不同组件在高层次上是如何工作的。
- 解释了竞争条件产生的原因。
- 省略了
S3、foreign keys、worker等技术术语的使用，这些术语对解释没有实际价值。 - 只在必要时使用专业术语（如果我们再努力一点，就可以省略 “服务”）。
- 不使用专业术语，详细解释问题的全部来龙去脉后，再解释问题的结果，让读者充分理解其影响。
5. 尽可能从最高层次思考真正的问题
认识到我们缺乏这种能力是至关重要的，因为这是改进的第一步。
你想向一个不理解行和列之间区别的人解释 SQL 存储过程是如何工作的吗？这对于一个客户经理来说重要吗？
真正的问题可能是系统无法以反映客户账户状态的方式检索数据，而不是存储过程有错别字。
6. 不要用技术术语来掩饰你缺乏理解
如果你不明白为什么某些代码行会影响业务，或者业务规则到底是什么，请与他人讨论问题，尝试找出问题所在。找人帮你（小黄鸭）可能是个好主意。但是，你们不是在调试问题，而是在讨论问题，直到双方都清楚地了解发生了什么。
不要害怕向产品经理、技术负责人、工程经理、总监、CTO或任何其他可用人员提问。这些对话将比你试图独自弄清楚企业应用程序应该如何工作更快地解决问题。
如果贵公司有文档（大多数情况下都没有），请花些时间看看其他人对这个特定系统写了什么。
7. 迭代
重新阅读你刚才写的内容并加以改进，是否有道理？是否清晰明了？你是否已经做了足够的工作，以高层次的流程来传达系统中正在发生的事情？如果你说得很慢，奶奶能听懂吗？
如果你不确定自己是否清楚地表达了问题，可以联系朋友，问问他们是否理解你想表达的意思。
他们可能不是百分百理解，但肯定能知道哪些地方让人困惑。这样你就能知道哪些地方需要用前面的步骤重新编写，直到你有一个完整的、万无一失的书面解释。
如果你能自信地说，你刚才写的东西通俗易懂，那么你就大功告成了！
值得这么麻烦吗？
我知道，工程师在工作中会遇到成千上万种情况，但对于这种微不足道的情况，用几段文字来描述这个过程太过复杂了。那又何必呢？
我最喜欢的软件编程定义之一是，它是一种传达意图的方式。
虽然与人交流和与计算机交流是截然不同的，但它仍然是一种交流。提高这项技能很可能会让你通过代码更清晰地传达自己的意图，而这本身就是非常值得的。
软技能不仅能让你成为一个更可靠的人，还能让你在各个层面上表现得更好，即使是那些你认为与社交互动完全无关的层面。
