编写指南
本页说明帮助文档的写法与提交要求。开始撰写前,请先阅读栏目首页的索引表,确认专题归属。
与使用文档的分工
| 栏目 | 内容 | 维护者 |
|---|---|---|
| 使用文档 | 启动器的功能、限制与操作步骤 | 项目维护者 |
| 帮助文档 | 具体场景下的完整操作流程 | 社区 |
使用文档给出功能清单与限制,本栏目给出完成一项任务的完整过程。两者不一致时,以使用文档与程序的实际行为为准,并在 Issue 中指出本栏目的错误。
WARNING
截图是本栏目的必要条件,并非可选项。截图中的文字须清晰可辨,字体须为系统默认字体。缺少截图,或文字无法辨认、字体难以识别的教程不予合并。
收录范围
| 专题 | 典型页面 |
|---|---|
| 下载与安装 | 如何下载安装包、如何选择架构、如何覆盖升级 |
| 账号与登录 | 如何登录微软账号、如何添加离线账号 |
| 游戏与版本 | 如何安装游戏版本、如何安装 Forge 与 Fabric |
| 模组与资源 | 如何安装模组、如何导入整合包、如何更换资源包 |
| 联机 | 如何开局域网、如何加入服务器 |
| 插件 | 如何安装插件、如何编写第一个插件 |
| 设置与优化 | 如何调整内存、如何切换渲染器 |
上表为常见专题,不构成限制。未列入的内容可以自行新增专题,须同时满足三条:涵盖一类操作、范围可用一句话概括、至少能承载两个页面。仅在单次环境中成立的写法差异,写在同一页面内即可,不必另立专题。
流程较长、单页难以承载的内容,也可另开专题:把各阶段拆成页面收进该专题,在专题首页按顺序排列入口,不将全部步骤集中于单页。
本栏目面向 Android 版本,截图取自 Android 真机或 Android 模拟器。Windows 与 macOS 不承载启动器的操作,仅在后期处理截图时使用,见在电脑上处理截图。
以下两类不收录:单一报错的原因分析,写入常见问题或 Issue;程序内部实现,写入开发者栏目。
开始之前
素材清单
| 项目 | 说明 |
|---|---|
| GitHub 账号 | 提交页面需要,注册免费 |
| 设备信息 | 机型、Android 版本、运行内存 |
| 启动器版本 | 在「设置 → 关于」中查看 |
| 游戏与加载器版本 | 例如 1.20.1 与 Fabric 0.15.11 |
| 截图设备 | 与教程对应的 Android 真机或模拟器,界面语言、字体与主题取默认值 |
| 已验证的解法 | 至少在自己设备上成功一次 |
末行为必要条件。未在自己设备上验证通过的步骤不写入页面,未确认的推测在 Issue 中讨论。
操作之前
请先在未安装插件、未改动设置的环境中完整执行一次流程,操作过程中同步截图。事后补拍易遗漏步骤,也易记错界面。
截图前固定设备语言、主题与字号。主题使用启动器首次启动时的默认主题,字体保持系统默认。中途更改会使同一篇教程中的截图前后不一致。
截图要求
以下为硬性要求,提交前逐条核对。
尺寸与清晰度
- 使用设备自带的截图功能,不以相机拍摄屏幕
- 宽度不低于 720 像素,长边不低于 1280 像素
- 不缩放,不裁切至低于上述尺寸
- 格式使用 PNG。JPG 在文字边缘产生噪点,小字易模糊
- 图片不经聊天软件二次转发。转发会重新压缩,文字出现彩色噪点
- 图中文字在 100% 显示比例下可直接辨认,无须读者放大查看
界面文字
- 界面字号保持系统默认,不调小字号以容纳更多内容
- 界面语言与正文一致,同一页面内不混用中文与英文界面
- 弹窗、提示与按钮上的文字完整入图,不裁去半行
- 正文引用的数值清晰可见,例如版本号、安装路径、端口
字体要求见下节。更换系统字体或安装字体包后,界面与官方默认外观不一致,读者无法对照自身设备。
字体
- 界面字体保持系统默认。不更换系统字体,不启用主题字体包,不使用第三方字体模块
- 标注文字使用系统自带的中文无衬线字体:Windows 用微软雅黑,Android 用思源黑体或 Roboto,macOS 与 iOS 用苹方
- 不使用艺术字、手写体、书法体与卡通体,不使用描边、渐变、阴影与发光效果
- 不以装饰性符号代替箭头,例如表情、星号、图案与字符拼成的指示
- 标注字号不小于 14 像素,与界面文字接近,不超出界面文字
- 同一页面的字体与字号统一,不逐图更换。字号前后不一,读者会误以为界面在流程中途发生过变化
判断依据为:文字在手机屏幕上能否直接辨认。字形带装饰、笔画粘连或需费力辨识的字体,即使外观美观,亦不采用。
主题与外观
- 使用启动器首次启动时的默认主题,不切换主题与配色方案
- 不启用自定义主题、图标包与字体包。界面与官方默认外观不一致时,读者无法对照自己的设备
- 系统启用深色模式时,请先关闭再截图。深色与浅色混排,会使同一流程的截图看似来自不同版本
- 同一专题下的所有页面使用同一主题,不逐页更换
- 裁去桌面与壁纸,个人图片不入图
- 全屏弹窗与侧栏面板须完整入图,不遮住标题
内容
- 一图对应一步,图上的界面与文字步骤一致
- 仅保留操作区域,裁去状态栏与无关界面
- 图中出现的版本号、界面名称与正文写法一致
- 同一流程的截图保持同一方向与同一缩放比例
标注
- 需点击的位置加方框,需输入的位置加箭头
- 标注颜色全局统一,使用一种(红色或橙色),线宽 2 像素
- 多步操作可用序号 ①②③ 标出先后
- 标注不得遮挡按钮文字与输入框内容
- 箭头指向目标控件本身,不指向空白处,一条标注只说明一处
- 方框贴合控件边缘,不跨越两个控件,不压住控件边框
- 线条平直。以鼠标或触控笔配合截图工具的矩形、箭头绘制,不使用手绘抖动笔迹
- 标注与界面颜色对比明显。深色界面可改用浅色描边,但同一页面内保持一致
- 序号与箭头所指的操作顺序一致,不多标,不漏标
符号本身也须清楚可辨。箭头端部完整、方框四角闭合、序号不带多余装饰;符号模糊或残缺时重绘标注,不得保留。
在电脑上处理截图
截图须取自 Android 设备或 Android 模拟器。Windows 与 macOS 仅用于后期标注与打码,不作为截图来源。
| 系统 | 可用工具 |
|---|---|
| Windows | 「截图工具」截取,「画图」绘制方框与箭头 |
| macOS | Shift + Command + 4 截取,「预览」的标记工具绘制方框与箭头 |
- 标注文字使用上述系统的默认字体,不安装第三方字体
- 不使用带花体字、贴纸、滤镜与边框的标注应用
- 处理完成后导出 PNG,不再经社交软件转发
打码
下列内容必须遮盖:账号名与头像、邮箱与手机号、真实姓名、服务器地址与端口、机器码与设备序列号、其他玩家的昵称。
- 打码属于正当处理。因隐私遮盖的截图照常计入截图数量,不因此判为不合格
- 不得因隐私顾虑删除截图或改用文字描述。缺失截图仍按不合格处理
- 使用纯色块完全覆盖,遮盖范围略大于原文字,边缘不留半个字符
- 不使用模糊、马赛克与半透明蒙层。上述处理在小尺寸下仍可能被还原
- 同一页面的遮盖色一致,与界面颜色有明显对比
- 遮盖后保留操作所需的上下文,例如遮去账号名而保留输入框与按钮
- 一处内容在多张图中出现时,每张图都要遮盖,不得只遮第一张。读者常从中间某张图开始看
文件与图片的位置
每个页面使用一个目录,入口文件为 index.md,截图置于同一目录。
help/
└── install/
└── first-game/
├── index.md 如何安装第一个游戏版本
├── 01-open-download.png
├── 02-select-version.png
└── 03-confirm.png正文使用相对路径引用同目录图片。
图片与页面放在同一目录,构建时会一并处理并改写为正确的引用地址。不得将图片放入 public/ 后再以 /help/... 引用:这类写法不会随构建改写,站点更换域名或改到子路径后可能失效。
一页教程的结构
页面依次为:标题、适用说明与信息表、前置条件、操作步骤、结果确认、遇到问题。各节不写背景介绍、版本沿革与个人经历。
1. 适用说明与信息表
标题下先写一句适用情况,例如「适用于首次安装、尚未创建任何实例的读者」,随后给出信息表。
| 项目 | 内容 |
|---|---|
| 适用版本 | ZPCL 1.5.5 及以上 |
| 适用设备 | Android 11 及以上,arm64 |
| 更新日期 | 2026-11-21 |
- 版本写启动器版本,游戏与加载器版本放在正文对应步骤
- 设备写系统版本与架构;受内存限制的流程另列最低内存
- 更新日期写最后一次核对截图的日期,改图或改步骤后同步更新
- 表下不加说明段落,需要解释的内容写入前置条件或正文
2. 前置条件
仅在确有必须先完成的步骤时写。每条说明做什么、做到什么程度,并给出链接。只写「已登录账号」而不说明登录方式与所需状态,读者无法判断是否已满足。
- 链接可指向本栏目任一专题的页面,不限于本页所属的专题
- 逐条写清,不以「完成准备工作」一句概括
- 没有前置条件时省略本节,不写「无」
3. 操作步骤
按顺序编号,每步一个小标题,写动作本身,例如「1. 打开下载页」。标题下说明操作位置与所得结果,三句以内。一步配一张截图,截图紧随文字。
- 编号连续,不跳号。跳号会让读者以为中间漏了一步
- 按钮与菜单名使用界面原文,加引号,不自行改写。改写后读者在界面上找不到对应文字
- 需等待时写明判据,例如进度条结束、界面跳转
- 同一步需在两个位置操作时,拆为两步,各配一图
- 步骤中涉及的选项与默认值一并写出,例如内存保持默认值
流程较长时按阶段分节,不压缩步骤。拆节与拆页的判断见合并成合集。
4. 结果确认
写出完成后可见的现象,供读者判断操作是否成功,例如「实例页出现新条目」「进度条走完并进入主界面」。一段,两句以内。不写「无报错即成功」这类空泛结论。
5. 遇到问题
列出本条流程常见的失败点与判断依据,三条以内。需要展开排错过程的,链接到常见问题的对应条目,不在本页重述。
完整示例
以下为一份可直接套用的页面骨架,展开后可复制源码。该示例不生成独立页面,仅在折叠块中展示。
展开查看示例页源码
# 如何安装第一个游戏版本
适用于首次安装、尚未创建任何实例的读者。
| 项目 | 内容 |
| --- | --- |
| 适用版本 | ZPCL 1.5.5 及以上 |
| 适用设备 | Android 11 及以上,arm64 |
| 更新日期 | 2026-11-21 |
## 前置条件
- 已登录账号:先[登录微软账号](/help/account/microsoft/),或[添加离线账号](/help/account/offline/)并填写用户名
- 剩余存储空间不少于 2 GB,含游戏文件与运行库
## 操作步骤
### 1. 打开下载页
点击底部导航栏的「下载」,进入版本列表。

### 2. 选择游戏版本
在列表中选择目标版本后,点击「安装」。

## 结果确认
「实例」页出现新条目,点击「启动」后进入游戏主界面。
## 遇到问题
启动失败时,查阅[常见问题](/faq)中的对应条目。与其他页面的关联
撰写前应先确认本页在流程中的位置。判断依据为:完成本页的操作,是否以另一页的完成为前提。
| 关系 | 处理 |
|---|---|
| 前置条件,未完成则本页无法继续 | 写入「前置条件」,每一条附对应页面的链接 |
| 后续步骤,本页完成后通常紧接进行 | 页尾「延伸阅读」给出链接,按操作顺序排列 |
| 同一动作的其他情况 | 本页以一句话说明差异,展开内容置于对应页面 |
| 功能名称、限制与版本差异 | 链接到使用文档,不在本栏目重述 |
规则如下。
- 前置条件缺少链接视为不合格。只写「已登录账号」而不给出登录页面的链接,读者无法确定应在何页开始操作
- 同一操作只在一处完整表述,其余页面改为链接。重复书写会在程序更新后出现多份互相矛盾的说明
- 站内链接使用绝对路径,例如
/help/account/microsoft/。跨目录的相对路径在页面移动后失效,不应使用 - 依赖关系不得成环。甲页依赖乙页、乙页又依赖甲页时,将共用步骤写成独立页面,两页均在该步骤处链接
- 一页内多次提及同一页面时,只在首次出现处加链接
- 尚未写成的页面不写链接,在索引表中保留「待补充」,避免构建因死链失败
专题与索引
栏目按两层组织:专题与页面。
- 专题:一类操作,对应侧栏的一级分组,落为
help/<专题>/,同时占索引表的一行 - 页面:一项具体操作,对应侧栏的二级条目,落为
help/<专题>/<页面>/index.md
专题与页面的名称在侧栏使用中文,目录使用英文短词。
help/
├── install/ 下载与安装
│ ├── choose-arch/ 如何选择安装包架构
│ └── upgrade/ 如何覆盖升级
├── account/ 账号与登录
│ ├── microsoft/ 如何登录微软账号
│ └── offline/ 如何添加离线账号
└── mods/ 模组与资源
└── install-mod/ 如何安装模组侧栏与目录一一对应。
{
text: '帮助文档',
items: [
{ text: '栏目介绍', link: '/help/' },
{ text: '编写指南', link: '/help/writing' },
{
text: '下载与安装',
collapsed: false,
items: [
{ text: '如何选择架构', link: '/help/install/choose-arch/' },
{ text: '如何覆盖升级', link: '/help/install/upgrade/' },
],
},
],
}新增页面时须同时改动三处:创建目录与 index.md、在侧栏登记、在栏目首页的索引表更新该专题的入口。新增专题时同样要改这三处,索引表需补一行。
遗漏登记的后果各不相同。仅创建页面而未在侧栏登记,页面可以访问,但不会出现在侧栏;仅在侧栏登记而未创建页面,构建因死链失败;索引表未更新,读者无法从栏目首页找到该专题。
侧栏层级最多两级。超过两级后,读者难以定位,也不适合手机端阅读。
合并成合集
拆分与合并按读者的目标判断,不按步骤数量判断。
| 情况 | 处理 |
|---|---|
| 一页即可完成一个目标,中途不需其他页面的前提 | 写成一页 |
| 流程较长,目标单一,中途无需离开当前界面 | 仍在一页,用二级小标题分段,页首列出节序 |
| 流程跨越多个目标,或中途需重启、切换应用、等待下载 | 按目标拆页,每页可独立完成一个目标 |
| 同一目标下分支明显,例如设备、游戏版本或加载器的差异较大 | 在同一专题下分别成页 |
| 某一方向已成体系,页面持续增多 | 另开专题收拢相关页面,专题首页按阶段排列入口 |
不设步骤数量上限。步骤较多的流程不必压缩,也不删减必要截图,按阶段分节即可:准备、下载、安装、验证各自成节,页首列出节序。
判断是否拆页的依据是目标是否唯一:读者完成本页后能否达成一项可描述的结果。同一任务的多个阶段留在同一页,不同任务各自成页。
多个页面共用同一前置步骤时,链接到该步骤所在的帮助页面;尚无对应页面时先写成独立页面,其余页面在「前置条件」中链接该页,不在各页重复叙述。
拆分后每页须能独立阅读。读者从任意一页进入,均可完成该阶段的操作。
以「安装整合包」为例,其中「下载整合包」「导入实例」「分配内存」各自达成不同的结果,应各自成页;三页共用的「安装游戏版本」已有对应页面,各页在「前置条件」中说明并链接该页。
提交
- Fork 仓库
Jinby71/ZPCL-docs - 新建分支,按上面的目录结构添加
index.md与截图 - 在
.vitepress/config.mts的「帮助文档」分组登记,并在栏目首页索引表中补充入口 - 提交 Pull Request,说明验证设备、系统版本、启动器版本,并附一张完成后的效果截图
措辞与格式要求见贡献指南。文档仓库的写作规范对社区页面同样适用。
不收录的内容
- 未在自己设备上验证通过的步骤
- 缺少截图的步骤
- 文字模糊、使用非系统默认字体或标注难以辨认的截图
- 更换过主题、字体或图标包的截图
- 对项目立场的推测
- 需付费、邀请码或非公开渠道方可获取的资源
- 他人的账号、机器码与个人信息
