描述问题的目的不是把事情的经过讲一遍，而是让对方能够理解、能够判断、能够直接动手处理。本文整理出描述问题时必须遵守的原则、必须提供的信息、应当避免的做法和值得提倡的做法，并附上一份可以直接套用的描述模板。

背景：我们经常需要向他人说一件事，例如报告一个反馈、或是提一个 bug、安排一个任务、或者是请求一个功能、创建一个需求等等。表达的方式有语音、文字聊天、通过表单提交等多种，无论那种方式都是重灾区。我们经常看到有人因为描述不清晰，而导致他人无法理解或者造成了一些不必要的浪费，甚至让看的人感到头晕眼花、昏昏欲睡以至于心情十分不好。我们也经常在 GitHub 的仓库里看到维护者创建了 issue 模板，就是为了规范 issue 的描述，使 issue 的描述更加清晰、更加方便。在一些购物平台或者政企网站上也会看到一些问题反馈通道里同样精心设计了详细的表单，要求按照某种格式或者提供某些信息，以便优化服务体验和解决问题。

那么，如何描述清楚一个问题，才能使他人能够理解、能够方便地解决问题呢？

注意：以下部分内容由 AI 生成！

一、先想清楚：描述问题的目的是让对方能行动

一份描述是否合格，可以用三个问题来检验：

1. 看得懂吗：不了解背景的人，能不能读懂在说什么？
2. 判断得了吗：对方能不能据此判断严重程度，判断问题大概出在哪个环节？
3. 干得成吗：对方能不能直接开始处理，而不是先回来问你十几个问题？

合格的描述通常由三部分组成：

• 事实：发生了什么，在什么条件下发生，有多确定；
• 期望：本应该是什么样子；
• 诉求：希望对方做什么，是修复、评估、给建议，还是仅仅记录在案。

二、必须遵守的原则

以下几条是硬要求，缺失任何一条，都会让对方多花时间，甚至沿着错误的方向排查。

1. 事实与推测分离。写清楚哪些是亲眼观察到的现象，哪些是你的猜测。猜测要标注“我推测”，不能当作结论写。
2. 一次只描述一个问题。两个不相关的问题混在一段话里，很容易只处理其中一个，也无法分别跟踪和关闭。
3. 结论前置。先说结论和诉求，再展开过程。对方往往在读到第三行时就要开始做判断。
4. 给出可复现的最小路径。环境、版本、前置条件、操作步骤缺一不可。“我这儿复现不了”的问题，等于无法修复的问题。
5. 说清期望与实际。有对比才有问题定义，“点击保存本应提示成功，现在返回 500”，比“保存功能有问题”有用得多。
6. 不假设对方拥有你的上下文。你屏幕上看到的、脑子里想的，对方都看不到。
7. 保持可验证。每一句关键描述都应该能被别人验证：命令、日志、链接、截图、时间点。
8. 说清影响与时效。影响哪些人、影响多大、最晚什么时候需要解决，这决定了对方先做哪件事。

三、必须提供的信息

四、应当避免的做法

1. 只丢一句话结论，如“系统坏了，你看一下”。对方的第一句回复必然是问“哪里、什么时候、怎么坏的”。
2. 只描述自己的方案，而不描述真正的问题。例如直接要求“帮我给这个字段加个索引”，但真正的问题可能是这个查询本身不该这么写。把自己的解法当成需求，很容易让双方一起走偏。
3. 把现象、猜测、抱怨和诉求揉在一段话里，让对方自己从中提取信息。
4. 大段粘贴日志却不标重点，或者只发截图不贴文本。日志要截取关键部分并注明看哪一行；纯图片无法被搜索、复制和引用。
5. 用模糊的限定词代替信息，如“偶尔”“有时候”“好像”“不太稳定”。应该换成频率、条件和时间点：“10 次里有 2 次”“只在负责人字段为空时”。
6. 隐瞒自己已经做过的操作。为省事不说自己改过配置或数据，会让对方在错误的前提下排查，浪费大量时间。
7. 把多个互不相关的问题打包成一个任务或一个工单。
8. 缺少环境信息，或者默认对方知道，例如“和昨天那个一样”。
9. 挤牙膏式补充信息。先发一句话，等对方追问才一点点给出信息，沟通成本会成倍增加。
10. 夹带情绪和指责，如“这么简单的功能都能写错”。情绪不解决问题，只会让接手的人不愿深入排查。
11. 只在口头或语音里说一遍，不留文字记录。没有记录的问题既无法跟踪，也无法沉淀为经验。
12. 事后不回收。问题解决了却不补充原因和结论，下一个人遇到同样的问题时还要从头再来。

五、值得提倡的做法

1. 使用模板。GitHub 的 issue 模板、工单表单、故障复盘模板，价值就在于让人在写的时候不遗漏关键信息。
2. 标题写具体：位置 + 条件 + 现象。“文章详情页在 MySQL 8.0 下保存草稿返回 500”优于“保存有问题”。
3. 先自查一轮再提问。写明做过哪些基础排查、得到什么结论、排除了哪些可能，让对方从你的结论上继续，而不是从零开始。
4. 给出最小复现。几条命令、几行代码就能复现，胜过一整段文字描述。
5. 证据兼顾文本与图片。日志和报错用文本给出并标注关键行，截图的处理方式见第六节。
6. 明确标注不确定的部分，例如“这一条我不确定，需要你帮忙确认”，让确定的结论和待验证的猜测各归各位。
7. 说明影响面而不只是现象。是所有人都受影响，还是只有特定角色受影响，这会直接改变优先级。
8. 语气直接但不失分寸。不需要客套，也不要指责，把精力放在信息本身上。
9. 结论回收。问题解决后补充根因和处理方式，让这条记录变成可以被搜索、被复用的经验。
10. 发送前站在对方视角复读一遍：如果我只看到这段文字，能不能立刻开始干活？

六、文字与图片的混排

截图能省掉大量文字，但用得不好，反而会让对方看不懂、找不着、对不上。下面几条是混排时的基本要求。

1. 图片是佐证，不是主体。文字部分要能独立读懂，图片只用来验证文字里的结论。关键报错务必以文本形式给出，不要只发截图，否则对方既没法搜索，也没法复制去查。
2. 圈出重点，而且只圈重点。用红框、箭头或高亮标出关键的那一到两处，并让标注指向具体位置（哪一行日志、哪个字段、哪个按钮）。整屏画满圈，等于没有标注。
3. 每张图配一句图注。图注写清“这张图能看出什么”，例如“图 2：保存后返回 500，注意响应头里的 X-Request-Id”，而不是只写“截图”。
4. 图文顺序一一对应。先出现文字说明，再紧跟对应的图；正文描述的顺序要和图片出现的顺序一致，不要让读者自己去找哪句话对应哪张图。
5. 多图要编号。用“图 1”“图 2”编号，并在正文里显式引用，如“见图 2”。图多了以后，编号是唯一可靠的对应关系。
6. 一段文字尽量只对应一张图。一对多的写法最容易对不上；确实是同一处的多个状态（如操作前、操作后），就在图上加序号标签，并与正文的步骤号保持一致。
7. 需要对比时，把两幅图并到一张里。把“期望结果”和“实际结果”左右并列，再分别标注，比一上一下两张孤立的图更容易看出差异。
8. 图要完整到足以判断。保留必要的上下文，例如浏览器地址栏、时间戳、完整的报错行，不要只截报错的后半句；同时把敏感信息（账号、令牌、手机号、内网地址）遮挡掉。
9. 图要清晰。不要用被压缩到看不清文字的缩略图，必要时放大关键区域或单独再截一张局部图。
10. 操作类问题优先用录屏或动图。但同样要在文字里说明看哪一步、看哪个动作，而不是丢一个视频让对方自己找。
11. 别把图放在会失效的地方。IM 里的图片会过期、临时链接会失效，重要证据要随工单一起落到可长期访问的位置。

七、一份可直接套用的模板

### 标题：<位置> + <条件> + <现象>
- 环境：<系统 / 版本 / 浏览器 / 相关配置 / 时间点>
- 前置条件：<需要什么数据、账号、配置>
- 复现步骤：
  1. <第一步>
  2. <第二步>
- 期望结果：<本应该是什么样>
- 实际结果：<现在是什么样，含报错原文>
- 证据：<日志片段 / 截图 / 链接；日志标出关键行，截图编号并圈出重点>
- 复现频率：<必现 / 10 次中 2 次 / 只在并发时>
- 已做的排查：<做过什么，得到什么结论，排除了什么>
- 影响与优先级：<影响范围，是否阻塞，期望何时解决>
- 诉求：<希望对方做什么>

八、不同场景下的取舍

原则不变，详略可以调整：

九、小结

描述清楚一个问题，本质上是降低对方理解与判断的成本：把事实说准，把期望说明，把诉求说清，把验证路径给足。做到这一点，问题能不能被快速解决，往往在开口的那一刻就已经决定了大半。把问题描述清楚不仅不会浪费时间，反而能节省双方的时间。