常见问题文档写作模板
更新时间: 2026/07/23
在Gitcode上查看源码一个FAQ一般由三部分组成:
FAQ = 问题现象 + 可能原因 + 处理措施
问题分为复杂问题和简单问题,部分简单问题中,标题已经说清楚了“问题现象”和“可能原因”,就可以省略重复部分。
一般FAQ分为以下两类:
故障处理类
咨询类(含特性原理/规格 /概念咨询、功能使用咨询)
故障处理类
标题:一句话简要描述问题的最终现象
问题现象
从用户角度出发,描述用户可感知的报错 。包括:问题出现的场景、现象、条件等。
(复杂问题可选)如有问题复现的完整操作流程,也在这个小标题下呈现。
可能原因(可选)
明确问题的根因。如果不同的原因对应不同的解决措施,需明确分点列举。
解决措施
Step-by-step方式写作,保证可执行性。
以“动宾句式”的操作步骤为主,有时 候还需要说明“操作目的”与当前步骤的“操作现象”。
理清逻辑关系(合理分层),并列关系采用无序列表,顺序关系(前后有依赖关系)采用有序列表。
代码示例(可选)
展示核心代码,提供可运行的代 码片段。 如果是步骤执行代码,可与解决措施中的步骤合并。
参考链接(可选)
附指南/API参考/Sample等赋能套件的资料链接,方便开发者拓展阅读。
咨询类
标题:以用户的疑问点切入,需要含有具体的特性关键词
无需分隔子标题,直接答复实现方案、对应的规格约束等。如果有代码示例辅助解释,可以直接在解决方案后提供简单的示例代码片段。
参考链接(可选)
附指南/API参考/Sample等赋能套件的资料链接,方便开发者拓展阅读。