使用Confluence如何输出一份结构清晰 & 可读性高的测试文档？

一、前言

很多小伙伴们 ， 会有输出文档的好习惯 ；但 如何 输出一份 结构清晰&可读性高 的测试文档 / 帮助文档呢 ？

你写的流程文档 / 帮助文档 / 使用教程 ，别人看完了之后能上手操作吗 ？

你会 灵活使用 confluence 文档编辑中的 状态、表情 、 宏 …吗 ？

如何让文档看起来更美观 ？

如果不太熟练，快上车！

二、背景

编写文档时，可以先交代一下编写文档的背景、目的、让大家阅读起来 一目了然 ，一下子明白：这篇文档的背景 + 目的 + 主题 ，例子如下：

工作中通过使用 Confluence 宏及插件，可以使文档看起来更简洁规范，有的时候也会事半功倍。

三、定义

如何才能是一篇好的文档，我认为，例如一个某业务流程文档看过之后，不需要沟通就能完成测试及使用，就是一个好文档。

好的技术文章，是让符合阅读条件的读者，在良好阅读体验的情况下，看懂学会甚至掌握文章要传达的信息。

有些人写文档 不接地气，没有考虑到别人看不看得懂、能不能顺利理解，后果是，文档虽全，但没人有耐心理解消化，最后还是都跑来问你，不胜其烦。

四、必看

要写一篇什么样的文档 ？
首先是要明确这个文档的主题，主要说清楚一个什么问题。

比如写 某需求的业务逻辑 文档的话 ，自己要对这块需求先由系统的了解，再整理出相关的流程图

可以整理自己的思路，对这个产品中的需求点，测试点，要知其然，更要知其所以然。

输出的文档，主要针对受众是谁 ？
知道你的读者是哪些人，他们的需求是什么，对产品的背景了解基础如何等等；

基于此你知道文档要包含哪些内容，哪些部分要详细，哪些要弱化，语言要用怎样的风格

大多数技术写作人员都会犯这样的错误：想当然认为所有读者都一样或者所有读者都跟自己一样。

这也是好多开发/测试人员写出来的文档读者看不懂的原因之一，对读者认识不够，一些以为读者懂的知识，其实读者根本不明白。

你输出这样的一份文档目的是什么 ？
比如输出一份：某需求的业务逻辑文档

你的目的是 让读者简单了解这块的业务逻辑

还是 看完之后读者从头到尾很清楚为什么有这块业务&业务逻辑是怎么样的

还是 明白业务逻辑的基础上可以对这块进行上手使用 ？

怎么写一篇可读性高的文档？
写文档时，要结合产品的需求和大概的实现流程，最好是贴图来解释一些比较难理解的地方，有图有注释，这样更好理解。

对于文档中，自己认为比较重要的地方，需要用显著标记出来，这样让看的人有重点。

如何提高技术写作能力？
以上只是简单摸摸皮毛，想入门的话，大家快戳这里：https://www.zhihu.com/question/21853187

五、宏调用

方式一：在菜单栏中点击 + 选择宏

方式二：键盘快捷方式，英文状态下的 “{” +宏名称

六、常用宏

编写文档时，内容可以 以各种各样的形态呈现，建议多使用可视化的形式呈现，例如：表格

七、具体宏

---

01 状态宏

添加 状态宏 步骤：

01、点击菜单栏 → 状态

02、

---

02 展开宏

添加 展开宏 步骤：

01、点击菜单栏 → 其他宏
02、右侧栏选择：格式化 → 选择：展开

03、插入宏

---

03 信息宏

04 提示宏

05 注意宏

06 警告宏

07 无面板

使用单一间隔字体在面板内显示文本，没有其他格式装饰。

08 定制面板

可自定义：面板标题、边框风格、边框颜色、边框像素宽度、背景色、标题背景色、标题文本颜色

您可以为一个颜色，例如十六进制值，如 #FF00FF 输入十六进制值时，您将需要包含＃符号。有关常规信息，请参见 http://web.chacuo.net/

列举几种经典色：蓝色：#0000FF 红色：#FF0000 紫色：#FF00FF 黄色：#FFD700

09 代码块

对源代码或XML块进行格式化的宏。

可自定义：折叠、显示行号、语法高亮、标题、主题…

---

10 目录宏

添加 目录宏 步骤：

01、点击菜单栏 → 目录宏

02、设置目录级别。设置完后 建议预览目录

03、比如你只想让 标题 1 显示在目录上

设置 最小标题级别 与 最大标题级别都是 1 即可~

具体怎么调试，自己玩玩~

---

11 添加导航

添加 导航 步骤：

01、点击菜单栏 → 其他宏

02、右侧栏选择：导航 → 选择：Easy Heading Free

03、保存

---

12 添加表情

添加 表情 步骤：

01、点击菜单栏 → 表情符号

02、某些 场景 可以 用表情来代替

03、效果

---

13 在线编辑Excel

添加 在线编辑Excel 步骤：
01、点击菜单栏 → 其他宏
02、右侧栏选择：格式化 → 选择：Spreadsheet → 确定
注意：
01、文档标题是必填，不填写无法保存哦~
02、编辑完文档记得点击：保存

---

14 绘制图

画图可以用 draw.io
draw.io evaluation version

添加 draw.io 步骤：
01、点击菜单栏 → draw.io Diagram
02、点击 Blank 新建一个空白的画布（也可以选择合适的模板）
03、编辑好画布内容后，保存并退出

---

15 添加表格

16 插入链接

第 1 种 ：先上传附件，想把这个附件链接贴在文档中

*步骤如下：

01 、插入链接

第 2 种：插入网络上的Web链接
*步骤如下：

01 、插入链接

02、选择Web链接 → 将网络上的Web链接粘贴在 地址中 ，再给链接文字取个标题 ，插入即可

03、示例

第 3 种：插入confluence链接 ，直接复制粘贴即可 。

---

17 JIRA过滤器

添加 JIRA过滤器 步骤：

01、点击菜单栏 → 其他宏

02、右侧栏选择：开发 → 选择：插入Jira图表

03、选中：JIRA问题/过滤器

04、进入JIRA - 某筛选器 列表 - 点击 “高级”

05、复制 JQL 粘贴在 JIRA过滤文本框中

06、效果

八、最后

别光顾着文档好看，还是需把重点放在内容上，多多关注内容的含金度，易读性。

多去问问看文档的人，这么写能不能看懂，用什么形式写更容易懂，哪些地方不用太详细，哪些地方要多说几句…