Skip to content

编写指南 ​

本页说明帮助文档的写法与提交要求。开始撰写前,请先阅读栏目首页的索引表,确认专题归属。

与使用文档的分工 ​

栏目内容维护者
使用文档启动器的功能、限制与操作步骤项目维护者
帮助文档具体场景下的完整操作流程社区

使用文档给出功能清单与限制,本栏目给出完成一项任务的完整过程。两者不一致时,以使用文档与程序的实际行为为准,并在 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「截图工具」截取,「画图」绘制方框与箭头
macOSShift + Command + 4 截取,「预览」的标记工具绘制方框与箭头
  • 标注文字使用上述系统的默认字体,不安装第三方字体
  • 不使用带花体字、贴纸、滤镜与边框的标注应用
  • 处理完成后导出 PNG,不再经社交软件转发

打码 ​

下列内容必须遮盖:账号名与头像、邮箱与手机号、真实姓名、服务器地址与端口、机器码与设备序列号、其他玩家的昵称。

  • 打码属于正当处理。因隐私遮盖的截图照常计入截图数量,不因此判为不合格
  • 不得因隐私顾虑删除截图或改用文字描述。缺失截图仍按不合格处理
  • 使用纯色块完全覆盖,遮盖范围略大于原文字,边缘不留半个字符
  • 不使用模糊、马赛克与半透明蒙层。上述处理在小尺寸下仍可能被还原
  • 同一页面的遮盖色一致,与界面颜色有明显对比
  • 遮盖后保留操作所需的上下文,例如遮去账号名而保留输入框与按钮
  • 一处内容在多张图中出现时,每张图都要遮盖,不得只遮第一张。读者常从中间某张图开始看

文件与图片的位置 ​

每个页面使用一个目录,入口文件为 index.md,截图置于同一目录。

text
help/
└── install/
    └── first-game/
        ├── index.md                  如何安装第一个游戏版本
        ├── 01-open-download.png
        ├── 02-select-version.png
        └── 03-confirm.png

正文使用相对路径引用同目录图片。

md
![打开下载页](./01-open-download.png)

图片与页面放在同一目录,构建时会一并处理并改写为正确的引用地址。不得将图片放入 public/ 后再以 /help/... 引用:这类写法不会随构建改写,站点更换域名或改到子路径后可能失效。

一页教程的结构 ​

页面依次为:标题、适用说明与信息表、前置条件、操作步骤、结果确认、遇到问题。各节不写背景介绍、版本沿革与个人经历。

1. 适用说明与信息表 ​

标题下先写一句适用情况,例如「适用于首次安装、尚未创建任何实例的读者」,随后给出信息表。

项目内容
适用版本ZPCL 1.5.5 及以上
适用设备Android 11 及以上,arm64
更新日期2026-11-21
  • 版本写启动器版本,游戏与加载器版本放在正文对应步骤
  • 设备写系统版本与架构;受内存限制的流程另列最低内存
  • 更新日期写最后一次核对截图的日期,改图或改步骤后同步更新
  • 表下不加说明段落,需要解释的内容写入前置条件或正文

2. 前置条件 ​

仅在确有必须先完成的步骤时写。每条说明做什么、做到什么程度,并给出链接。只写「已登录账号」而不说明登录方式与所需状态,读者无法判断是否已满足。

  • 链接可指向本栏目任一专题的页面,不限于本页所属的专题
  • 逐条写清,不以「完成准备工作」一句概括
  • 没有前置条件时省略本节,不写「无」

3. 操作步骤 ​

按顺序编号,每步一个小标题,写动作本身,例如「1. 打开下载页」。标题下说明操作位置与所得结果,三句以内。一步配一张截图,截图紧随文字。

  • 编号连续,不跳号。跳号会让读者以为中间漏了一步
  • 按钮与菜单名使用界面原文,加引号,不自行改写。改写后读者在界面上找不到对应文字
  • 需等待时写明判据,例如进度条结束、界面跳转
  • 同一步需在两个位置操作时,拆为两步,各配一图
  • 步骤中涉及的选项与默认值一并写出,例如内存保持默认值

流程较长时按阶段分节,不压缩步骤。拆节与拆页的判断见合并成合集。

4. 结果确认 ​

写出完成后可见的现象,供读者判断操作是否成功,例如「实例页出现新条目」「进度条走完并进入主界面」。一段,两句以内。不写「无报错即成功」这类空泛结论。

5. 遇到问题 ​

列出本条流程常见的失败点与判断依据,三条以内。需要展开排错过程的,链接到常见问题的对应条目,不在本页重述。

完整示例 ​

以下为一份可直接套用的页面骨架,展开后可复制源码。该示例不生成独立页面,仅在折叠块中展示。

展开查看示例页源码
md
# 如何安装第一个游戏版本

适用于首次安装、尚未创建任何实例的读者。

| 项目 | 内容 |
| --- | --- |
| 适用版本 | ZPCL 1.5.5 及以上 |
| 适用设备 | Android 11 及以上,arm64 |
| 更新日期 | 2026-11-21 |

## 前置条件

- 已登录账号:先[登录微软账号](/help/account/microsoft/),或[添加离线账号](/help/account/offline/)并填写用户名
- 剩余存储空间不少于 2 GB,含游戏文件与运行库

## 操作步骤

### 1. 打开下载页

点击底部导航栏的「下载」,进入版本列表。

![打开下载页](./01-open-download.png)

### 2. 选择游戏版本

在列表中选择目标版本后,点击「安装」。

![选择版本](./02-select-version.png)

## 结果确认

「实例」页出现新条目,点击「启动」后进入游戏主界面。

## 遇到问题

启动失败时,查阅[常见问题](/faq)中的对应条目。

与其他页面的关联 ​

撰写前应先确认本页在流程中的位置。判断依据为:完成本页的操作,是否以另一页的完成为前提。

关系处理
前置条件,未完成则本页无法继续写入「前置条件」,每一条附对应页面的链接
后续步骤,本页完成后通常紧接进行页尾「延伸阅读」给出链接,按操作顺序排列
同一动作的其他情况本页以一句话说明差异,展开内容置于对应页面
功能名称、限制与版本差异链接到使用文档,不在本栏目重述

规则如下。

  • 前置条件缺少链接视为不合格。只写「已登录账号」而不给出登录页面的链接,读者无法确定应在何页开始操作
  • 同一操作只在一处完整表述,其余页面改为链接。重复书写会在程序更新后出现多份互相矛盾的说明
  • 站内链接使用绝对路径,例如 /help/account/microsoft/。跨目录的相对路径在页面移动后失效,不应使用
  • 依赖关系不得成环。甲页依赖乙页、乙页又依赖甲页时,将共用步骤写成独立页面,两页均在该步骤处链接
  • 一页内多次提及同一页面时,只在首次出现处加链接
  • 尚未写成的页面不写链接,在索引表中保留「待补充」,避免构建因死链失败

专题与索引 ​

栏目按两层组织:专题与页面。

  • 专题:一类操作,对应侧栏的一级分组,落为 help/<专题>/,同时占索引表的一行
  • 页面:一项具体操作,对应侧栏的二级条目,落为 help/<专题>/<页面>/index.md

专题与页面的名称在侧栏使用中文,目录使用英文短词。

text
help/
├── install/                  下载与安装
│   ├── choose-arch/          如何选择安装包架构
│   └── upgrade/              如何覆盖升级
├── account/                  账号与登录
│   ├── microsoft/            如何登录微软账号
│   └── offline/              如何添加离线账号
└── mods/                     模组与资源
    └── install-mod/          如何安装模组

侧栏与目录一一对应。

ts
{
  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、在侧栏登记、在栏目首页的索引表更新该专题的入口。新增专题时同样要改这三处,索引表需补一行。

遗漏登记的后果各不相同。仅创建页面而未在侧栏登记,页面可以访问,但不会出现在侧栏;仅在侧栏登记而未创建页面,构建因死链失败;索引表未更新,读者无法从栏目首页找到该专题。

侧栏层级最多两级。超过两级后,读者难以定位,也不适合手机端阅读。

合并成合集 ​

拆分与合并按读者的目标判断,不按步骤数量判断。

情况处理
一页即可完成一个目标,中途不需其他页面的前提写成一页
流程较长,目标单一,中途无需离开当前界面仍在一页,用二级小标题分段,页首列出节序
流程跨越多个目标,或中途需重启、切换应用、等待下载按目标拆页,每页可独立完成一个目标
同一目标下分支明显,例如设备、游戏版本或加载器的差异较大在同一专题下分别成页
某一方向已成体系,页面持续增多另开专题收拢相关页面,专题首页按阶段排列入口

不设步骤数量上限。步骤较多的流程不必压缩,也不删减必要截图,按阶段分节即可:准备、下载、安装、验证各自成节,页首列出节序。

判断是否拆页的依据是目标是否唯一:读者完成本页后能否达成一项可描述的结果。同一任务的多个阶段留在同一页,不同任务各自成页。

多个页面共用同一前置步骤时,链接到该步骤所在的帮助页面;尚无对应页面时先写成独立页面,其余页面在「前置条件」中链接该页,不在各页重复叙述。

拆分后每页须能独立阅读。读者从任意一页进入,均可完成该阶段的操作。

以「安装整合包」为例,其中「下载整合包」「导入实例」「分配内存」各自达成不同的结果,应各自成页;三页共用的「安装游戏版本」已有对应页面,各页在「前置条件」中说明并链接该页。

提交 ​

  1. Fork 仓库 Jinby71/ZPCL-docs
  2. 新建分支,按上面的目录结构添加 index.md 与截图
  3. 在 .vitepress/config.mts 的「帮助文档」分组登记,并在栏目首页索引表中补充入口
  4. 提交 Pull Request,说明验证设备、系统版本、启动器版本,并附一张完成后的效果截图

措辞与格式要求见贡献指南。文档仓库的写作规范对社区页面同样适用。

不收录的内容 ​

  • 未在自己设备上验证通过的步骤
  • 缺少截图的步骤
  • 文字模糊、使用非系统默认字体或标注难以辨认的截图
  • 更换过主题、字体或图标包的截图
  • 对项目立场的推测
  • 需付费、邀请码或非公开渠道方可获取的资源
  • 他人的账号、机器码与个人信息

WARNING

本栏目的内容由社区提交,不代表项目维护者的意见。涉及账号、付费与设备安全时,请先阅读使用条款与隐私政策。

ZPCL Launcher 是 Zalith Launcher 2 的非官方修改版,遵循 GPLv3 开源协议