如何写参考话题
参考话题的作用
参考话题的主要目的是提供查阅型的信息，也就是那些用户在执行任务时可能会临时查找的内容，比如参数列表、命令语法、字段说明、配置选项等。
它不像任务话题那样教你怎么做，也不像概念话题那样解释原理，而是像“速查表”，让用户快速找到具体信息。
参考话题适合包含哪些内容
- 参数或字段的名称和说明
- 命令或语法格式
- 配置选项及其默认值
- 键盘快捷键、菜单项、按钮功能
- 错误代码及含义
- 限制条件、兼容性说明等
举例： 如果你写的是一个软件的帮助文档，参考话题可能包括“配置文件参数说明”“命令行选项列表”“数据库字段定义”等内容。
参考话题的写作建议
聚焦一个主题
每个参考话题只介绍一类信息，不要混合多个不相关的内容。 例如，“数据库字段说明”是一个话题，“命令行参数”是另一个，不应放在一起。
信息要结构清晰、易于查找
- 使用表格、列表或分组方式组织内容
- 每一项都要有明确的标题或标签
- 避免大段文字堆砌，尽量让用户一眼就能找到所需信息
使用一致的格式
保持每一项信息的格式一致，比如每个参数都用“名称 + 类型 + 描述”的格式。这样用户在查阅时更容易理解和比较。
标题要具体
参考话题的标题应使用名词或名词短语，准确描述内容。 不推荐：“参考信息” 推荐：“网络设置参数”“导出命令语法”“用户角色类型”
避免解释性内容
参考话题不是用来解释“为什么”，而是告诉用户“是什么”。如果需要解释，请放在概念话题中。
参考话题的常见形式
| 类型 | 示例内容 |
|---|---|
| 参数列表 | 参数名称、说明、默认值 |
| 命令语法 | 命令格式、可选项、示例 |
| 字段定义 | 字段名称、数据类型、用途 |
| 键盘快捷键 | 快捷键组合、对应功能 |
| 错误代码说明 | 错误编号、含义、可能原因 |
写参考话题的一句话秘诀
“参考话题是让用户在最短时间内找到最具体答案的地方。”
