PCLC Docs

简体中文

English

简体中文

English

主题

编写规范 ​

本文档用于说明 PCLC Docs 的内容编写规范，包括条目收录范围、行文视角、语言风格、格式要求、术语使用、示例写法以及参考标准等内容。

本文规范适用于 PCLC Docs 下的所有文档。除 PCL CE 外，若 PCL Community 后续维护其他项目、工具、服务或开发者文档，也应遵循本文规范。针对特定项目的专用规范，可以在对应项目文档中另行补充，但不应与本文的通用要求冲突。

所有新增文档和对既有文档的大幅修改，均应尽可能遵循本文规范。若因特殊情况无法完全遵守，应在 Pull Request 描述中说明原因，方便维护者审核。

一、编写前检查 ​

在创建新的帮助条目之前，应先确认该内容是否适合收录到 PCLC Docs 中。

1. 检查站内是否已有相关内容 ​

创建新条目前，应先在文档站点中搜索相关关键词，确认站点中尚未收录相同或高度重复的内容。

若已有相近内容，应优先考虑修改或补充既有页面，而不是创建新的重复页面。

2. 检查是否已有相关 Pull Request ​

创建新条目前，应查看文档仓库在 GitHub 上的 Pull Requests，确认没有其他贡献者正在编辑相同或相近内容。

若已有相关 Pull Request，可以在对应讨论中补充建议，或等待该 Pull Request 合并后再继续修改。

3. 确认内容与 PCL Community 及其项目有关 ​

新增条目必须与 PCL Community、PCLC Docs 或 PCL Community 维护的具体项目具有明确关联。

这里的“项目”包括但不限于：

  • PCL Community 维护的启动器或相关应用；
  • PCL Community 维护的核心库、工具链或开发组件；
  • PCL Community 维护的文档站点、规范文档或贡献指南；
  • 与上述项目直接相关，且用户或开发者确实可能需要了解的外部服务说明。

以下内容通常适合收录：

  • PCL Community 旗下项目的安装、配置和使用说明；
  • PCL Community 旗下项目中具体功能的说明或教程；
  • PCL Community 旗下项目的常见问题排查方法；
  • 与项目开发、文档贡献、项目规范相关的内容；
  • 与项目使用场景直接相关，且具有长期参考价值的外部服务说明。

以下内容通常不应收录：

  • 与 PCL Community 及其项目无直接关系的内容；
  • 仅适用于极少数特殊场景，且缺乏长期参考价值的内容；
  • 时效性过强、短期内可能失效的内容；
  • 与项目无关的纯 Minecraft 游戏机制说明；
  • 仅表达个人经验、个人观点或个人偏好的内容。

4. 区分 PCLC Docs 与 Minecraft Wiki ​

PCLC Docs 不是 Minecraft Wiki，不应收录纯游戏机制、玩法百科或与 PCL Community 项目无关的游戏教程。

若需要编写纯 Minecraft 游戏相关内容，应前往 Minecraft Wiki 教程页面。

例如，以下内容通常不适合收录到 PCLC Docs：

  • 如何击败末影龙；
  • 如何建造刷怪塔；
  • 如何制作红石电梯；
  • 某个 Minecraft 版本新增了哪些方块。

但如果内容与 PCL Community 项目的功能、使用场景或排障流程直接相关，则可以收录。例如：

  • 如何使用 PCL CE 安装 Minecraft；
  • 如何在 PCL CE 中安装 Mod；
  • 如何在 PCL CE 中配置 Java；
  • 如何排查 PCL CE 启动 Minecraft 失败的问题；
  • 某个项目依赖 Minecraft 资源结构时，对相关目录的必要说明。

5. 参考已有合格页面 ​

编写新页面时，可以参考站点中已经过审核的既有页面。

优先参考顶部未标注“需要重新整理格式”“需要优化排版”等提示的页面。这些页面通常已经经过维护者审核，可以作为结构、语气和排版的参考。

可以复制类似页面作为模板，但必须根据实际内容修改标题、正文、图片、链接和示例，不得保留与新页面无关的内容。

二、基本写作原则 ​

1. 使用官方视角 ​

文档内容代表 PCL Community 及对应项目的官方说明，因此应使用官方视角编写，不应使用个人视角。

不应使用“我”“我们觉得”“我推荐”“我的经验是”等个人化表达，除非该页面明确是署名文章、讨论记录或其他特殊说明页面。

错误示例：

text
我觉得这个功能很好用，你可以试试看。

推荐写法：

text
该功能可用于快速完成相关配置，适合需要重复执行相同操作的场景。

错误示例：

text
要修改这一堆条目，你去提交 Pull Request 后还得等审核才可以。

推荐写法：

text
若需要修改 PCLC Docs 中的文档内容，可以提交 Pull Request。提交后，仍需等待维护者审核。

2. 使用正式书面语 ​

文档应使用清晰、正式、稳定的说明文语言。应避免口语化、情绪化、玩笑式或社交媒体式表达。

不应使用以下表达方式：

  • “一堆”“乱七八糟”“很坑”“很离谱”等口语或情绪表达；
  • “你就无脑点下一步”“随便填一下”等不严谨表达；
  • “众所周知”“懂的都懂”等缺乏说明的信息；
  • “非常牛”“超好用”“强烈安利”等评价性表达。

错误示例：

text
这里会有一堆奇怪的问题，反正你重装一下就好了。

推荐写法：

text
若该步骤出现异常，可以尝试重新安装相关组件，并确认安装路径和版本是否符合要求。

3. 使用客观说明文体 ​

文档应以说明事实、解释步骤和描述结果为主，尽量避免剧情化、宣传化或评价性叙述。

错误示例：

text
整合包里有许多好玩的 Mod，但下载之后如何安装却成了大家的一大疑惑，这篇教程会教会你如何安装。

推荐写法：

text
下载整合包后，还需要完成导入或安装操作才能进行游戏。本文介绍在启动器中安装整合包的方法。

4. 避免主观评价 ​

除非确有必要，不应使用主观评价描述功能、软件、服务或用户行为。

错误示例：

text
这个方法最简单，也最适合小白。

推荐写法：

text
该方法操作步骤较少，适合首次配置的用户。

错误示例：

text
这个功能没什么用，不建议打开。

推荐写法：

text
若不需要该功能提供的相关能力，可以保持关闭状态。

5. 避免不必要的时效性叙述 ​

文档内容应尽量保持长期有效。涉及时间时，应使用明确日期，不应使用“今年”“最近”“新版”“目前”等容易过期的表达。

错误示例：

text
Mojang 在今年 4 月更新了 1.14，更新内容很多。

推荐写法：

text
Mojang 在 2019 年 4 月发布了 Java 版 1.14。

若内容确实具有时效性，应尽量注明具体版本、日期或适用范围。

三、受众与内容深度 ​

编写文档时，应根据页面面向的读者决定说明深度。

1. 面向普通用户的文档 ​

面向普通用户的文档应尽量详细说明操作路径、前置条件和可能结果。

适合包含以下内容：

  • 操作入口；
  • 每一步需要点击或填写的内容；
  • 操作完成后的预期结果；
  • 常见错误及处理方法；
  • 必要截图；
  • 对专业名词的简要解释。

示例：

text
打开对应项目后，进入“设置”页面。如果列表中没有可用配置项，可以点击“自动搜索”或“刷新”让程序重新扫描本机环境。

若文档只适用于某个具体项目，应在页面开头或相关章节中明确说明。

示例：

text
本文仅适用于 PCL CE。其他 PCL Community 项目可能不包含相同的设置入口。

2. 面向高级用户的文档 ​

面向高级用户、开发者或维护者的文档可以省略部分基础操作，但仍应保证说明完整、准确。

适合包含以下内容：

  • API 行为说明；
  • 配置项含义；
  • 参数说明；
  • 边界条件；
  • 兼容性说明；
  • 维护注意事项。

示例：

text
该配置项会在启动参数生成前读取。若需要影响实际启动参数，应确保配置写入发生在启动流程进入参数构建阶段之前。

3. 避免误判读者水平 ​

即使文档面向高级用户，也不应故意省略关键背景。若某个步骤失败会导致明显问题，应说明失败后的表现或排查方向。

错误示例：

text
配置好环境后直接构建即可。

推荐写法：

text
配置完成后，可以在仓库根目录运行 `dotnet build` 检查环境是否可用。若构建失败，应优先检查 SDK 版本、依赖恢复情况和本地网络环境。

四、术语与称谓 ​

1. 使用标准称谓 ​

文档中应使用统一、准确的标准称谓。涉及具体项目时，应以该项目的官方名称为准。

推荐写法不推荐写法
PCLC DocsPCLC文档、这个文档站
PCL CommunityPCL社区、PCL 群体
PCL CEpclce、社区版启动器
Minecraft我的世界、MC
Javajava
Mojangmj、mojang
Microsoft微软账号体系相关场景中不应写作 ms
Pull RequestPR 可在首次说明后使用
GitHubgithub、Github

若页面标题或上下文需要使用中文解释，可以在首次出现时写作：

text
Mod（通常也称为模组）

之后应在同一页面内保持一种写法，不应频繁混用。

2. 使用准确的软件和项目名称 ​

涉及具体项目时，应根据语境使用准确称谓。

  • 指代 PCL Community 整体时，应使用 PCL Community。
  • 指代文档站点时，应使用 PCLC Docs。
  • 指代具体项目时，应使用该项目的正式名称，例如 PCL CE。
  • 指代某个项目的界面或功能时，可以使用项目正式名称，也可以在上下文明确时使用“该项目”“启动器”“工具”等描述。
  • 若界面中实际显示的名称与项目正式名称不同，可以在操作说明中使用界面原文。

示例：

text
打开 PCL CE，进入“设置 → 启动器”页面。

示例：

text
在 PCLC Docs 中新增页面时，应确认该页面属于正确的项目目录。

若必须引用界面原文，应保持界面文本一致：

text
点击“新建档案”按钮。

3. 避免非标准缩写 ​

除非是项目中已经广泛使用且不易产生歧义的缩写，否则不应自行缩写专有名词。

错误示例：

text
进入 pclce 的设置页，如果没有安装 64 位 java，最多就只能分配 1G 内存。

推荐写法：

text
进入 PCL CE 的设置页。如果没有安装 64 位 Java，最多只能分配 1G 内存。

4. 数字与单位 ​

数字、单位和版本号应保持清晰。

推荐写法：

text
64 位 Java
1G 内存
Java 17
Minecraft 1.20.1

同一页面中应避免混用不同写法，例如不应同时出现 1G、1 GB、1GB。若无特殊原因，优先沿用对应项目界面中的写法。

五、中文、英文与空格 ​

1. 中英文之间应添加空格 ​

中文与英文、数字之间通常应添加半角空格。

错误示例：

text
进入PCLC Docs后，选择对应项目文档。

推荐写法：

text
进入 PCLC Docs 后，选择对应项目文档。

错误示例：

text
安装64位Java后可以分配更多内存。

推荐写法：

text
安装 64 位 Java 后，可以分配更多内存。

2. 中文标点外侧通常不加空格 ​

中文标点与中文之间不应额外添加空格。

错误示例：

text
打开设置 ， 然后选择启动器 。

推荐写法：

text
打开设置，然后选择启动器。

3. 中文引号与外部文字的连接 ​

中文引号与外部中文文字之间通常不添加空格。

推荐写法：

text
点击“开始安装”按钮。

如果引号内为英文界面文本，仍应根据句子结构保持自然排版。

推荐写法：

text
点击“New pull request”按钮。

4. 使用中文标点 ​

中文文档中应优先使用中文标点符号。

推荐写法不推荐写法
，,
。.
：:
；;
（）()
“ ”" "

错误示例：

text
打开 PCL CE 的设置页, 如果没有安装 64 位 Java, 最多只能分配 1G 内存.

推荐写法：

text
打开 PCL CE 的设置页，如果没有安装 64 位 Java，最多只能分配 1G 内存。

5. 代码、命令和路径使用半角符号 ​

代码、命令、路径、URL、配置键等技术内容应使用半角符号，并放入行内代码或代码块中。

推荐写法：

text
在仓库根目录运行 `pnpm install` 安装依赖。

推荐写法：

text
图片应放入 `public/contents/` 目录。

六、页面结构规范 ​

1. 标题层级 ​

每篇文档应只有一个一级标题，即页面标题。

推荐结构：

markdown
# 页面标题

## 一、一级章节

### 1. 子章节

#### 更细的说明

不应跳级使用标题。例如，不应在 ## 后直接使用 ####。

2. 标题应描述内容 ​

标题应准确概括该章节内容，不应使用过于口语化或含糊的标题。

不推荐：

markdown
## 一些东西

## 注意一下

## 其他

推荐：

markdown
## 准备工作

## 安装步骤

## 常见问题

3. 教程类页面结构 ​

教程类页面应按照读者实际操作顺序组织内容。

推荐结构：

markdown
# 页面标题

简要说明本文用途、适用对象和适用项目。

## 一、准备工作

说明开始前需要准备什么。

## 二、操作步骤

按实际顺序说明操作。

## 三、验证结果

说明如何确认操作成功。

## 四、常见问题

列出常见错误和解决方法。

4. 规范类页面结构 ​

规范类页面应优先按规则类别组织内容，而不是按操作流程组织内容。

推荐结构：

markdown
# 页面标题

说明规范适用范围。

## 规范用语说明

解释“必须”“应”“建议”等用语。

## 基本要求

列出通用规则。

## 分类规范

按内容类型列出具体规则。

## 附录

放置标准、参考链接或补充材料。

5. API 或开发者文档结构 ​

API 或开发者文档应优先说明概念、类型、参数、行为和边界条件，不应写成普通用户教程。

推荐结构：

markdown
# API 名称

说明 API 用途和适用范围。

## 概览

列出核心概念。

## 类型定义

说明类型、参数和返回值。

## 行为说明

说明调用效果和边界条件。

## 示例

提供必要代码示例。

七、段落与列表 ​

1. 段落应完整表达意思 ​

正文段落应使用完整句子，不应只堆叠短语或关键词。

不推荐：

text
打开设置。
选择 Java。
自动搜索。
完成。

推荐：

text
打开项目的设置页面后，进入 Java 管理相关选项。点击“自动搜索”后，程序会扫描本机可用的 Java，并将搜索结果显示在列表中。

2. 列表用于整理并列信息 ​

列表适合用于展示并列事项、检查清单或步骤，但不应替代必要说明。

不推荐：

markdown
## 准备工作

- Java
- 网络
- 账号

推荐：

markdown
## 准备工作

开始前，请确认本机已经安装可用 Java，并且网络环境可以访问需要下载的资源。如果需要登录特定服务，还应提前准备对应账号。

3. 步骤列表应有明确动作 ​

步骤列表中的每一项应说明具体操作，不应只写界面名称。

不推荐：

markdown
1. 设置
2. Java
3. 搜索

推荐：

markdown
1. 打开对应项目，进入“设置”页面。
2. 在侧边栏中选择“Java 管理”。
3. 点击“自动搜索”，等待程序扫描本机 Java。

4. 避免过长列表 ​

如果列表项过多，应考虑拆分为多个小节，或改为表格。

一般情况下，同一组列表不建议超过 10 项。若超过 10 项，应检查是否需要重新分组。

八、提示块与警告块 ​

文档中可以使用 VitePress 支持的提示块突出重要信息。提示块应服务于正文说明，不应替代正文，也不应被滥用。

PCLC Docs 中应优先使用 VitePress 默认支持的提示块类型：

类型用途
info用于补充说明背景、限制或上下文信息
tip用于提供有帮助但非必要的建议
warning用于提醒可能导致失败、异常或误操作的情况
danger用于强调可能造成严重后果、数据丢失或不可逆影响的操作
details用于折叠较长的补充说明、示例或可选内容

1. info ​

info 用于说明背景、限制或补充解释。该类型适合放置读者需要了解，但不一定影响后续操作的信息。

markdown
::: info 说明
该设置只影响当前项目配置，不会修改系统环境变量。
:::

说明

该设置只影响当前项目配置，不会修改系统环境变量。

2. tip ​

tip 用于补充有帮助但非必要的信息，例如推荐做法、效率提示或可选操作。

markdown
::: tip 提示
如果你不确定应该选择哪个 Java，可以优先使用程序自动搜索到的推荐项。
:::

提示

如果你不确定应该选择哪个 Java，可以优先使用程序自动搜索到的推荐项。

3. warning ​

warning 用于提醒可能导致失败、异常或误操作的情况。读者通常需要在继续操作前理解该提示。

markdown
::: warning 注意
修改该选项后，可能会导致已有配置无法正常使用。请确认理解其影响后再继续。
:::

注意

修改该选项后，可能会导致已有配置无法正常使用。请确认理解其影响后再继续。

4. danger ​

danger 用于强调可能造成严重后果的操作，例如数据丢失、配置损坏、无法恢复的修改等。

markdown
::: danger 危险
删除该目录会移除其中的所有本地配置和缓存文件。执行前请确认已经备份需要保留的内容。
:::

危险

删除该目录会移除其中的所有本地配置和缓存文件。执行前请确认已经备份需要保留的内容。

5. details ​

details 用于折叠较长的补充内容。适合放置不影响主流程阅读，但在特定情况下可能有用的说明、示例或排查信息。

markdown
::: details 查看更多说明
这里可以放置较长的补充说明、命令示例或排查步骤。
:::
查看更多说明

这里可以放置较长的补充说明、命令示例或排查步骤。

6. 不应滥用提示块 ​

若普通正文已经可以清楚说明，不应额外使用提示块。

不推荐：

markdown
::: tip
点击按钮即可继续。
:::

推荐写法：

text
点击“继续”按钮后，程序会进入下一步配置流程。

提示块中也不应放置过长的主要流程。若某段内容是读者必须阅读的正文，应直接写入普通段落或独立章节，而不是放入提示块中。

九、代码块与命令 ​

1. 代码块应指定语言 ​

代码块应尽量指定语言，以获得正确的语法高亮。

推荐写法：

markdown
```cmd
dotnet build
```
markdown
```yaml
name: CI Check
```

2. 不支持的语言应使用相近语言 ​

若站点高亮器不支持某种语言，应使用语法相近的语言。

例如，XAML 可以使用 xml：

markdown
```xml
<Grid>
    <TextBlock Text="Hello" />
</Grid>
```

3. 命令应注明运行位置 ​

如果命令必须在特定目录执行，应在代码块前说明。

推荐写法：

text
在仓库根目录运行以下命令：
cmd
pnpm install

4. 命令示例不应包含无关输出 ​

除非需要解释报错信息，否则命令代码块中只应保留命令本身，不应混入大量终端输出。

十、图片规范 ​

1. 图片应服务于说明内容 ​

图片应放在相关步骤附近，不应集中堆放在页面末尾。

不推荐：

markdown
## 图文示例

![图片](/contents/a.png)
![图片](/contents/b.png)
![图片](/contents/c.png)

推荐：

markdown
1. 打开对应项目，点击“新建档案”。

![新建档案入口](/contents/new-profile.png)

2. 选择“第三方验证”，然后点击“确认”。

![第三方验证选项](/contents/auth-type.png)

2. 图片描述应具体 ​

图片的替代文本应说明图片内容，不应只写“图片”。

不推荐：

markdown
![图片](/contents/settings-page.png)

推荐：

markdown
![设置页面](/contents/settings-page.png)

3. 图片路径 ​

文档图片应放在站点约定的资源目录中，并使用以 /contents/ 开头的路径引用。

推荐写法：

markdown
![角色管理页面](/contents/role-page.png)

4. 避免过度依赖图片 ​

图片只能辅助说明，不能代替正文。即使图片无法加载，读者也应能通过正文理解基本操作。

不推荐：

text
按图操作即可。

推荐：

text
在“角色管理”页面中点击“添加新角色”，然后在弹出的窗口中输入角色名。

十一、链接规范 ​

1. 站内链接 ​

链接到站内其他文档时，应优先使用相对路径。

推荐写法：

markdown
[技术规范](./guidelines.md)

2. 外部链接 ​

链接到外部网站时，应使用完整 URL，并确保链接来源可靠。

推荐写法：

markdown
[GitHub Pull Requests](https://github.com/PCL-Community/docs.pclc.cc/pulls)

3. 链接文本应说明目标 ​

链接文本应描述目标内容，不应使用“点击这里”“这个页面”等含糊表达。

不推荐：

markdown
详情请看[这里](./guidelines.md)。

推荐：

markdown
详情请参见[技术规范](./guidelines.md)。

4. 避免无依据外链 ​

除官方文档、项目仓库、标准页面和必要参考资料外，不应随意添加来源不明的外部链接。

十二、示例写法 ​

1. 示例应真实、简洁、可理解 ​

示例应尽量贴近实际使用场景，不应使用容易造成误解的虚构内容。

推荐写法：

text
进入项目的设置页面后，如果没有安装 64 位 Java，程序可能无法分配较高内存。

2. 错误示例与推荐写法 ​

需要说明格式或表达差异时，可以使用错误示例和推荐写法。

推荐格式：

markdown
错误示例：

```text
进入pclce的设置页,如果没有安装64位java,最多就只能分配1G内存.
```

推荐写法：

```text
进入 PCL CE 的设置页，如果没有安装 64 位 Java，最多只能分配 1G 内存。
```

3. 不应使用冒犯性或攻击性示例 ​

示例中不应包含攻击、嘲讽、歧视、引战或可能冒犯读者的内容。

十三、时效性内容 ​

1. 避免使用相对时间 ​

文档中不应使用“今年”“最近”“目前新版”等相对时间表达，除非页面会持续维护并明确标注更新时间。

不推荐：

text
今年 Mojang 更新了新的版本。

推荐：

text
Mojang 在 2024 年发布了对应版本。

2. 标注适用项目和版本 ​

涉及项目差异或版本差异时，应说明适用项目和适用版本。

推荐写法：

text
该功能适用于 PCL CE 2.9.0 及以上版本。

推荐写法：

text
本文仅适用于 PCL CE，不适用于 PCL Community 维护的其他项目。

若不确定具体版本，不应强行编写版本范围。可以改为说明现象或提醒读者以实际界面为准。

3. 谨慎编写临时性内容 ​

临时活动、短期公告、临时故障绕过方案等内容不宜写入长期文档。若确有必要，应明确标注适用时间和失效条件。

十四、内容维护要求 ​

1. 修改旧页面时应顺手修正明显问题 ​

修改旧页面时，如果发现明显错别字、失效链接、错误称谓或格式问题，可以一并修正。

但若修正范围较大，应单独提交或在 Pull Request 描述中说明，避免影响审核。

2. 不应无意义重排全文 ​

不应仅因个人偏好对已有页面进行大规模重排、重写或格式化。

若页面确实需要重新整理，应说明重写原因，例如：

  • 原页面结构混乱；
  • 步骤顺序不符合实际操作流程；
  • 内容明显过期；
  • 图片与正文严重脱节；
  • 多处表述不符合本文规范；
  • 页面内容已经不符合当前项目定位。

3. 保持页面长期可维护 ​

新增页面时，应考虑后续维护成本。若内容依赖外部服务、第三方界面或特定版本行为，应尽量减少不必要的细节绑定，并在必要处说明适用范围。

若页面仅适用于某个项目，应在页面开头或相关章节中明确说明。不要让读者误以为该内容适用于 PCLC Docs 下的所有项目。

十五、参考标准 ​

文档中的标点符号、中文夹用英文、格式细节应遵循以下标准和参考资料：

  • 《中华人民共和国国家标准——标点符号用法》（GB/T 15834-2011）；
  • 《中华人民共和国新闻出版行业标准——中文出版物夹用英文的编辑规范》（CY/T 154-2017）；
  • 维基百科——格式手册。

其中，标点符号和中文夹用英文的相关要求为强制要求。若本文规范与上述标准存在未覆盖的细节，应优先参考上述标准。

附录 ​

《中华人民共和国国家标准——标点符号用法》（GB/T 15834-2011） ​


您的浏览器不支持 PDF 预览，请 点击此处下载 后查看。

《中华人民共和国新闻出版行业标准——中文出版物夹用英文的编辑规范》（CY/T 154-2017） ​


您的浏览器不支持 PDF 预览，请 点击此处下载 后查看。

Released under the Creative Commons Attribution-ShareAlike 4.0 International Public License (CC BY-SA 4.0).

Copyright © PCL Community