常见问题/错误排查/Troubleshooting是技术文档中常见的内容类型，经常出现于用户指南、运维指南等技术文档中，指导用户或运维人员，在使用/运维产品过程中遇到问题时，如何排查解决问题。那么，如何写作常见问题/错误排查类内容呢？
大家好，我是睿齐，一个技术传播者，IT行业技术文档工程师。
用户问题＝常见问题？
在切入正题之前，我们先对齐一下基本共识。
关于常见问题，似乎存在着这样一个普遍的认识：是对用户提出的产品/技术问题的解答。但是，用户提出的问题五花八门，是不是所有提问，都要写入常见问题呢？
我曾经眼睁睁地看着，一个单一功能的产品，被活生生地写出上百条常见问题，类似于：
如何设置？如何获取？如何执行？如何查询？……
支持设备？支持环境？支持系统？支持架构？……
某接口某参数为某值是什么意思？……如此等等。
这样做的初衷和良苦用心我可以理解：每一个用户的提问，都有被认真对待、解答、积累，期望成为可被下一个用户复用的知识资源。然并卵。实践结果是：研发团队花费了巨大的时间、精力优化、整理、分类、维护常见问题，但是用户问题依然汹涌澎湃。
为什么常见问题失效了？
对于这个问题，技术支持工程师给出的答案往往简单粗暴：还能为什么？因为用户根本不看文档啊，尤其是付费用户，他们就喜欢提问题，被服务。——如果事实真相正如所言，那么用户的个人选择确实是我们不可控的部分；但是作为文档工程师要从可控的部分中找出并解决问题。
我们假设用户已经自行查阅了常见问题，但依然提出了重复的问题，那么可能的情况是：
用户没有找到需求的信息。
用户放弃查找需求的信息。
而究其原因是：信息过载。
信息量太大，反而找不到需求的信息。
信息量太大，直接给整不会了——想象一下，你是否也曾体验过，被海量信息淹没的恐惧？
所以，常见问题并不是越多越好，“少即是多（Less is More）”才是永远的追求。
用户为什么提问？
对于这个问题，技术支持工程师给出的答案依然简单粗暴：还能为什么？因为用户根本不看文档啊，尤其是付费用户，他们就喜欢提问题，被服务。——如果事实真相正如所言，那么用户的个人选择确实是我们不可控的部分；但是作为文档工程师还是要从可控的部分中找出并解决问题。
我们假设用户已经自行查阅了产品/技术文档，那么可能的情况是：
文档中未包含用户需求的信息。
文档中已包含用户需求的信息，但是不充分。
文档中已包含用户需求的信息，但是用户没有找到。
可见，用户之所以提出问题，根本原因往往在于技术文档的信息不满足，并不是缺少常见问题。因此，我们在分解用户问题时，不要单纯地增加常见问题，而是要将它作为技术文档的一部分，进行系统考虑。
其实，好的技术文档在最初设计的时候，就已经充分考虑了用户信息场景，尽可能最大化地包含了相关信息：
说明类（Concept）：解决“是什么”的问题。
操作类（Tast）：解决“如何做”的问题。
参考类（Reference）：解决技术细节的问题。
所以上文中提到的某单一功能产品的上百条问题，即便它们可能确实被用户反复提问，但都不是真正的常见问题，大概率只是技术文档的内容质量出了问题。
如何分解用户问题？
当我们处理用户提问，并试图反哺改进文档时，可以参考以下思路：
判断：当前文档是否已经提供相关信息？
否：则完善文档，补充相关信息。后续用户可通过文档获取信息，从而减少用户提问。
是：则进一步判断。
判断：当前信息是否清晰易见？
否：则优化文档，包括但不限于：
调整内容架构：避免信息隐藏过深，不易于查找；
添加注意事项：突出显示关键信息。
是：则说明文档本身不存在问题，可能是用户缺乏文档使用习惯或经验。
判断：判断当前问题是否经常被提问？
是：添加常见问题，便于用户多个方式解决问题。
否：忽略。
这样做可以优先完善了技术文档本身，最小限度地增加常见问题，从而保证内容极简。
什么是常见问题
跑题千里，其实只是想明确一点：当我们谈论“常见问题”的时候，我们究竟在谈论什么？
事实上，排除了技术文档已经解决的“是什么”、“如何做”以及技术细节的问题之后，留给常见问题的空间已然是不多了。
不过，技术文档提供的信息主要聚焦在产品的正常使用，而用户在实际使用过程中，可能会遇到各种各样的异常情况——处理异常，才是常见问题真正关注的问题。
如何写作常见问题
当我们明确了常见问题关注的范围，写作相关内容就简单多了。一般来说，常见问题可以有2种写作方法：
明确问题：详细描述问题的现场环境，提出相应解决方法。
模糊问题：简单描述问题现象，并通过一系列排查，帮助用户定位问题，并给出相应解决方法。类似于Debug的过程。
说明：上面这两个劳什子术语，是我自己定义的，希望已经充分解释清楚了。
常见问题通常推荐采用明确问题的写法。可以想见，站在用户立场，更希望能够快速、准确地定位问题，并得到相应解决方法；而不是屏气凝神地被人指导着自己去定位问题。但是在一些问题现象简单，影响因素复杂的问题场景，采用模糊问题的写法也是必要的。
明确问题
写作明确问题类常见问题的基本逻辑是：错误描述、问题分析和解决方法。
以上示例摘自阿里云，仅供参考
问题描述
错误描述，应尽可能细化粒度地描述错误场景，帮助用户结合自身情况，判断内容是否适用。
错误描述需充分考虑以下方面：
现场环境：说明引起错误发生的相关系统环境，包括但不限于硬件（如产品型号）、网络、操作系统、软件版本等。
业务阶段：如业务场景较多，说明出现错误的业务阶段。例如，注册、执行等。
报错内容：包括但不限于系统反馈的错误码、错误信息、指示灯/鸣笛告警等，可提供相关屏幕截图进行辅助说明。
问题分析
针对报错信息，给出问题分析，帮助用户理解出错原因。
解决方法
给出具体操作步骤，以达到指导用户按步骤操作，解决问题的目的。
模糊问题
写作模糊问题类常见问题的基本逻辑是：错误描述、错误排查和解决方法。
以上示例摘自阿里云，仅供参考
问题描述
描述问题现象。
问题排查
给出具体排查步骤，以达到指导用户按步骤操作，定位问题的目的。类似于Debug过程。
解决方法
给出具体操作步骤，以达到指导用户按步骤操作，解决问题的目的。
总结
常见问题，不是用户问答的大全集，而是作为技术文档的必要组成部分，聚焦于产品使用的异常处理，系统地组织信息，才能更好地发挥效用。
以上只是我对常见问题的个人理解，如有不同意见，欢迎交流。
其他推荐：
实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播从业者
品牌内容策划
自由摄影师
自由撰稿人
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
邮箱：hash_0813@163.com
5751
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
