Skip to main content

卷王使用手册写作指南

本文件是给 AI 或文档作者的写作说明，不会发布到线上。

目标读者​

  • 角色：企业/学校/机构的系统管理员，负责创建和管理问卷、考试等项目
  • 技术水平：非技术人员，熟悉基本的电脑操作和浏览器使用，不具备编程能力
  • 核心诉求：快速了解功能、快速完成配置，遇到问题能立即找到答案
  • 使用习惯：通常带着具体问题来查文档，不会从头到尾阅读

写作原则​

1. 任务导向，不是功能罗列​

每篇文档围绕「用户想完成什么任务」来组织，而不是「系统有什么功能」。

  • 好的标题：「创建第一份问卷」「设置白名单限制答题人员」
  • 避免的标题：「白名单模块功能说明」「问卷子系统概述」

2. 开门见山​

  • 第一段用 一句话 说清这个功能是什么、解决什么问题
  • 不要写「本文将为您介绍…」这类开场白
  • 不需要单独的「简介」「背景」「概述」小节

3. 操作步骤配截图占位​

  • 步骤控制在 3-5 步，超过 5 步考虑拆分
  • 用 ### 1. 步骤名 格式编号，不要用 1.1 1.2 这种层级编号
  • 截图由人工补充，AI 生成文档时用以下格式预留占位，说明需要截取的内容：
:::tip[图片占位]
截图：进入项目 → 设置 → 白名单页面，标注「开启白名单」开关位置
文件名：whitelist-enable.png
:::

占位规则：

  • 只写占位提示，不要写 ![]() 图片引用，图片文件不存在时会导致构建报错
  • 占位格式使用 :::tip 图片占位 区块
  • 占位内容中说明需要截取的页面、需要标注的操作区域、建议的文件名
  • 人工截图后，将图片放入同级 image/ 目录，再把占位替换为真实图片引用，例如 ![白名单开关](image/whitelist/whitelist-enable.png)
  • 写作阶段可以先直接引用截图软件导出的大 png/jpg
  • 文档写完后，统一运行 npm run optimize-help-images，脚本会自动压缩图片并把引用替换成 .webp
  • 每个关键步骤预留一张截图，非关键步骤可省略

4. 保持简洁​

  • 段落不超过 3 行
  • 能用列表说清楚的不用段落
  • 能用表格对比的不用文字描述
  • 不要重复系统界面上已经写清楚的文字

5. 用口语化的中文​

  • 用「你」而不是「您」
  • 用「点击」而不是「请点击」
  • 用「打开」而不是「开启/启用」（除非是系统中的按钮名称）
  • 避免「其」「之」「予以」「进行」等书面语

文档结构模板​

每篇功能文档遵循以下结构（可根据内容复杂度省略部分章节）：

# 功能名称

一句话说明功能用途。

## 使用场景             ← 2-3 个场景，帮用户判断是否需要此功能
## 操作步骤             ← 核心内容，配截图
## 进阶用法             ← 可选，高级配置或组合用法
## 常见问题             ← 2-3 个高频问题，用 <details> 折叠

各章节说明​

章节是否必须说明
一句话说明必须标题下方第一段，不加小标题
使用场景推荐用无序列表，2-3 条即可
操作步骤必须文档的核心，步骤 + 截图
进阶用法可选高级功能、组合技巧、与其他功能的联动
常见问题推荐用 <details> 标签折叠，不占主体篇幅

格式规范​

MDX 注意事项​

本项目使用 MDX（Markdown + JSX）格式，有以下特殊要求：

  • 图片占位统一使用 :::tip 图片占位，不要使用 JSX 注释或 HTML 注释
  • HTML 标签必须闭合：<br /> 而非 <br>，<img ... /> 而非 <img ...>
  • 花括号是特殊字符：如果要在正文中显示 { 或 }，需要用反引号包裹或转义为 {'{'}

Markdown 用法​

  • 按钮名称用 加粗：点击 发布 按钮
  • 菜单路径用 → 连接：进入 项目 → 设置 → 白名单
  • 系统中的专有名词用「」引号：开启「允许重复填写」
  • 代码、字段名、公式用反引号：字段编号为 q1

提示框使用​

:::tip
正面的建议、最佳实践、快捷技巧
:::

:::warning
需要注意的限制或容易出错的地方
:::

:::danger
可能导致数据丢失或不可逆的操作
:::

截图规范​

  • 截图放在同级目录的 image/ 文件夹中
  • 文件名使用英文小写 + 短横线，优先用有语义的名字：whitelist-enable.png
  • 写作阶段允许先保留原始 png/jpg，发布前统一转为 webp
  • 截图宽度建议控制在 1200-1600px，避免直接使用超大原图
  • 关键操作区域用红色矩形框标注
  • 发布前建议运行一次 npm run optimize-help-images

链接规范​

  • 引用其他文档时使用相对路径或绝对路径：[白名单](/help/settings/whitelist)
  • 通用设置被多个场景引用时，在场景文档中用一句话 + 链接指过去，不要重复写内容

写作检查清单​

写完一篇文档后，对照以下清单检查：

  • 第一段是否一句话说清了功能用途？
  • 操作步骤是否 ≤ 5 步？
  • 每个关键步骤是否配了截图？
  • 是否有不必要的「简介」「背景」「总结」章节？
  • 段落是否超过 3 行？能否用列表或表格替代？
  • 是否使用了口语化的中文？
  • 引用其他功能时是否用了链接而非重复内容？
  • 常见问题是否用 <details> 折叠了？
  • 图片占位是否使用了 :::tip 图片占位？
  • 所有 HTML 标签是否正确闭合？
Last updated on