在这几年的工作中，我会经常阅读和写技术方案文档，这些文档主要描述了解决某个特定问题的方法，其中文档好坏的一个决定性因素是文档对问题的陈述能力。
通常在文档顶部有一个问题陈述的段落，它的目的是阐明文档撰写背后的原因，只要你正在提出对系统进行变更，那么这将是你阐明动机的地方，特别是：
- 你希望你的团队成员支持你所做的事情
- 让读者更容易参与
- 有助于确定项目的边界
这是三个主要原因，用于说服你把问题陈述清楚，我们先展开聊下这三个。
你希望你的团队成员支持你所做的事情
为什么要写文档？写完为什么要发出来评审？文档的主要目的是说服并获得团队成员对解决问题方式的支持，你写文档一方面是向其他人传达你的意图，并希望得到反馈，此外更重要的是让大家相信这是值得做的。
如果你在提供反馈时不清楚作者的意图是解决什么问题，就很难提供反馈，甚至可能因为歧义导致不必要的争论，而且如果你的老板不清楚问题的实质，也很难对项目产生兴趣以及提供资源支持。
让读者更容易参与
首先，无论是你的团队成员还是其他团队的成员，大家都很忙！不要让他们做额外的工作去猜测你想做什么！把问题描述清楚更容易让大家参与并投入到讨论中，说 “xx 类的结构设计不好” 可能不太能激发大家的兴趣，而透过表象问题说 “我们的开发人员需要两周时间才能对 xx 流程进行更改” 则更容易引起兴趣。
能吸引大家参与到同一个会，这事就成了一半；如果与会的同时还有充分的讨论，那这事基本上就成了。
有助于确定项目的边界
项目设计中最棘手的问题之一是确立清晰的成功标准和衡量指标。项目什么时候完成？缺乏明确的标准是项目边界不断扩大的主要原因，一个好的问题陈述不能说完全解决这个问题，但你至少应该制定一版可供讨论的预期指标出来，只要能确定预期，项目的边界问题就算解决了。
在后续的方案设计中，权衡一件事的优先级、重要性就可以围绕最终的预期来展开，反之则可以将它降级或者日后再说。
好了，到这里希望可以说服你关于一个好的问题陈述的重要性，那么决定是不是一个好的问题陈述的关键要素又有哪些呢？大概也有三点：
- 它用与业务目标关联的方式描述问题
- 可量化
- 不要预设解决方案
咱们继续展开聊一聊。
它用与业务目标关联的方式描述问题
描述问题时，将要解决的问题与对业务的影响关联起来非常重要，开发人员往往难以理解的是，他们遇到的问题好像就应该对其他人显而易见。
比如：“xx 流程每分钟出现 xx 个线上异常”。
这不是很好的陈述方式，因为 “异常” 本身很可能不是业务方关心的情况，它对用户的实际影响是什么？如果你想让读者搞懂它的重要性，你可以将描述优化为：
“访问 xx 流程的 20% 用户会遇到错误，导致他们流程走不下去，最终放弃 xx 行为，每月潜在损失 xx”
或者说：
“开发人员每月需要花费 xx 个小时响应与 xx 流程路径相关的页面问题”
我们不仅描述异常现象，也要描述异常的影响，并将它们放在业务方关心的事物上，企业需要赚钱、需要聚焦、需要确保工作高效，通过这些描述，更容易让大家参与其中。
可量化
在前面写到确定项目的边界时提到了标准、指标，这是因为可量化的描述可以真正帮助大家相信这件事值得做，可以更容易做出优先级决策。
与其说 “要变更 xx 很复杂、维护成本很高”，不如量化大家浪费的时间，或者是暗示错误产生的成本。对开发人员来说要做到这点很难，内心往往会抵触，一是因为担心写下无意义的数字，二是要达到实际数字确实很困难。如果你也有这种感觉，只需要记住：把它当成是问题规模判断和优先级确定的练习，实际的精确度并不重要，诚实的猜测和努力的践行就够了。
不要预设解决方案
更常见的情况是文档里根本没有写问题陈述，短短几句 “寒暄” 后，直奔试图建立的东西，比如 “公司没有一种衡量代码质量的方法”，这个陈述的问题在于它没有描述一个问题，而是描述了一个解决方案 “有衡量代码质量的方法”。
不要假设你的读者都认为有衡量方法很重要，而是描述没有会出现什么问题！
“线上问题数比行业平均水平高 xx%，根据调研，我们怀疑没有衡量代码质量的方法可能是一个原因”。
在这个陈述中，我们将其从 “解决方案” 转变为实际问题，并描述了为什么需要的动机。
最后
希望对写出更好的文档有所帮助！