跳到主要内容

指南规范

Guides Banner

为了确保我们 ZAP-Docs 上的内容始终保持一致的质量和风格，我们制定了一系列在创建或编辑文档内容时必须遵循的规范。你必须严格遵守这些规范，以确保你的建议和最终的 Pull Request 能够快速被处理。更重要的是，这将保证我们的读者在阅读和跟随指南时，获得更好且一致的高质量体验。

我们的指南贡献规范分为以下几个部分：

  • 结构
  • 风格
  • 格式
  • 术语

建议你在开始撰写任何内容之前，至少浏览一遍这些部分。如果在创作过程中对某些内容的处理方式有疑问，也可以随时参考这里。

结构​

我们 ZAP-Docs 上的所有指南都遵循相对一致的结构，通常以简短的介绍和任何前置条件或准备步骤开头，接着是主体内容，最后是简短的结论。

根据不同类型的指南，结构有时会有所调整。这可以在你初次提交建议时与 ZAP-Docs 团队讨论。你可以通过标题部分了解如何使用标题，都是通过传统的 Markdown 语法完成的。

我们通常期望看到的结构包含以下标题：

  • 页面标题 (H1) - 通过页面顶部的 title 元数据设置。
  • 介绍 (H2) - 简短的1-2句，说明指南主题，最重要的是解释本指南的目标。
  • 准备工作 (H2) - 该标题可选。仅当有某些前置条件或准备步骤需要读者先完成时才需要。例如，如果用户必须先登录服务器，可以在这里引用我们的SSH 初始访问指南。或者介绍所需的软件和/或硬件要求，或者提供如何准备某些软件（如防火墙）的快速说明。建议浏览我们的ZAP-Docs 网站，查看是否已有相关指南并链接过去。
  • 主体内容 (H2) - 指南的第一个主要部分。很多情况下，这会是安装，接着会有多个子章节详细说明各个步骤。但也不一定，比如信息类指南可能会有不同的主体内容。
  • 可选：子主题 1 (H3)
  • 可选：子主题 2 (H3)
  • ...
  • 可选：另一个主题 (H2)
  • 结论 (H2) - 作为指南的最后部分，用1-3句总结读者已成功完成的内容，并提供支持团队的联系方式，以便读者遇到问题时寻求帮助。
子标题的使用（H3 & H4）

鼓励使用 H3 标题在主要的 H2 章节内创建子章节，将较大的内容块进一步组织成有条理的部分。上文的主体内容部分就是一个示例。

你也可以使用 H4 标题。如果你想创建另一个子章节但不希望它显示在右侧的章节导航中，H4 非常有用。如果你需要将 H3 章节进一步拆分成更小的部分，也可以使用 H4。

如果使用子标题，通常建议在父标题下至少有两个或更多子标题，否则只有一个子标题通常没有意义。

未来，我们会提供预设的 Markdown 模板，作为创建新页面的起点，敬请期待。

标题​

指南的标题应简短，基于你所写指南的整体目标。仔细考虑读者在完成指南后将实现什么，比如安装某个软件或提供某个特定主题的信息。

标题应以指南所属的产品类别作为前缀，这也应是你在侧边栏中放置该指南的分类。你可以查看同一分类下的其他指南，参考它们的前缀。

例如，针对 VPS 产品的一个好标题示例是：VPS: SteamCMD Linux 设置

介绍​

指南的介绍应简洁明了，通常为1-2句。内容应简要描述当前主题，最重要的是说明本指南将向读者展示什么，告知最终目标。

针对 SteamCMD 的理想介绍示例：

  • 第一句：SteamCMD 是安装多款游戏专用服务器（如 Palworld、Enshrouded 等）必备的重要工具。
  • 第二句：本指南将介绍如何首次在 Linux 服务器上安装 SteamCMD。示例中使用 Ubuntu，但其他发行版的步骤应类似。

如示例所示，介绍简要总结了本指南的相关主题，并向读者展示了完成指南后的整体目标。

准备工作​

准备工作部分用于明确读者在跟随指南之前必须完成的前置条件。这可能包括软件或硬件要求、准备某些软件（如防火墙）的说明，或指导用户通过 SSH 或 RDP 登录服务器。

强烈建议浏览我们的ZAP-Docs 网站，查找是否已有涵盖或相关的准备步骤的指南。如果已有相关指南（例如SSH 初始访问），应链接并告知读者先完成该步骤。

常见的前置条件包括：

  • 所需软件（如 Git、Node.js、Python、Docker）
  • 帮助读者获取基础知识的教程（如其他 ZAP-Docs 页面）
  • 用户账户，如 API
  • 必要设置（如 DNS/SSL）

反向代理指南的示例：

要设置反向代理，你需要一台 Linux 服务器来托管代理服务器，并且应能连接到它。如果需要帮助，请参考我们的[SSH 初始访问](vserver-linux-ssh.md)指南。你还需要拥有一个域名。对于计划使用的每个子域，应创建一个指向 Linux 服务器 IP 地址的 `A` 记录。

主体内容​

现在开始撰写指南的主体部分。你可以自由使用 H2、H3 和 H4 标题来合理组织内容。通常，H2 用于大章节，H3 和 H4 用于细分子章节。

很多涉及软件安装的指南会使用安装作为 H2 标题，并细分为多个 H3 子章节。如果你不确定如何构建结构，不用担心，我们会在你提交建议阶段协助规划合理的结构。

每个章节内，建议添加简短的开头和结尾过渡语句，让读者随时了解自己已完成的内容和接下来要做什么。当然，最后一个主要章节不一定需要结尾语，因为它自然过渡到结论部分。

示例过渡语：

  • 开头语：本节将带你完成软件的配置过程，定制符合你的需求。
  • 结尾语：配置完成并保存文件后，接下来请进入下一节，设置管理员账户并开始使用软件。

通过这些过渡语，读者能获得重要的上下文信息，确保指南流畅。记住，写作时应始终使用第二人称（如“你将创建”），而非第一人称，以保持读者的参与感和关注点。

结论​

最后一节是指南的结论。用1-3句总结读者已成功完成的内容，并提供进一步阅读或相关指南的链接，帮助读者扩展该主题的知识。

最好链接已有的 ZAP-Docs 指南，尤其是那些自然衔接你指南的内容。还建议提供支持团队的联系方式，方便读者遇到问题时寻求帮助。

优秀结论示例：

你已成功在 Linux 服务器上完成软件的安装！建议浏览本节中的 Linux 服务指南，安装更多服务。

如有任何疑问或需要帮助，欢迎随时联系我们的支持团队，我们每天都在线为你服务！🙂

风格​

ZAP-Hosting 文档的写作风格秉持高质量、实用且易于理解的原则，支持广泛的主题，适合各种经验水平的读者。

技术性 & 准确性​

我们的文章力求技术准确且紧跟行业最新信息。我们期望文章不仅帮助用户实现学习、搭建或配置的最终目标，还能让他们理解每一步的意义。你作为作者，指南中的每一步都应有明确目的和解释，必要时提供额外选项和参数说明。始终让读者了解他们正在做什么以及为什么这么做。

作者应仔细校对并测试指南，确保技术正确且功能正常后再提交 Pull Request。ZAP-Hosting 文档团队会在适当时阅读并测试你的指南，确保内容一致且事实正确，或在发现错误时提出改进建议。

提示

我们强烈建议作者在提交前使用拼写检查工具确保语法和拼写无误。推荐使用：https://languagetool.org/

实用性 & 有用性​

读者读完文章后，应能从头到尾学会、搭建或配置某项内容。我们的指南支持各种经验水平的读者，因此你的贡献应全面覆盖主题，确保读者获得知识或完成任务。作为作者，应详尽说明所有必要细节，包括前置条件。只有在 ZAP-Docs 没有相关文档或需要补充额外技术知识时，才可引导读者访问外部网站。外部链接不得指向竞争对手的文档。

友好、正式 & 全面​

我们希望文档风格前瞻且友好，便于所有读者理解，同时保持正式。整个指南中，写作语气应适合所有读者，无论经验或语言背景。

由于指南主要帮助读者学习并达成目标，建议使用第二人称（如“你需要...”）而非第一人称（如“我认为...”），以保持读者的参与感和关注点。

最后，所有作者必须遵守我们的行为准则，确保指南对所有人友好包容，无论年龄、种族、性别认同、经验水平、国籍、宗教、政治立场、性取向、社会经济状况或技术选择。避免使用任何可能冒犯的语言或涉及上述敏感话题的内容。

格式​

我们的文档采用广泛使用且相对简单的 Markdown 标记语言格式。下面介绍我们使用的格式及其用法。

提示

想了解更多 Markdown 功能示例和详细说明，请访问 Markdown Guide。

标题​

标题是分隔页面内容的重要格式选项。主标题为 H1，但你不应在正文中使用它，而是通过页面顶部的 title 元数据设置。

在指南中，H2 用于划分主要章节，H3 用于划分子章节。例如，将一个大章节拆分为多个步骤。H4 较少使用，但可用于进一步拆分子章节，且不会显示在右侧目录结构中。

信息

如果使用子标题（如 H3），请确保同一章节内有两个或以上同级标题，否则属于错误用法。

标题使用示例：

## 安装
H2 - 主要章节

### 下载游戏文件
H3 - H2 的子章节

#### 通过 SteamCMD
H4 - H3 的子章节

#### 通过 GitHub 手动下载
H4 - H3 的子章节

### 准备配置
H3 - H2 的子章节

### 启动服务器
H3 - H2 的子章节

行内 Markdown​

我们使用多种行内格式提升指南可读性，适合不同技术水平的读者。以下介绍常用格式及用法。

加粗文本​

加粗主要用于强调信息，例如：

  • 步骤间的上下文切换
  • 主机名、凭证和用户名
  • 关键术语

用双星号包裹文本实现加粗，如 **hello there** 显示为 hello there。

斜体​

斜体主要用于引入新的技术关键词，例如：我们今天将设置一个 反向代理。

用单星号包裹文本实现斜体，如 *ZAP-Hosting - More POWER!* 显示为 ZAP-Hosting - More Power!。

行内代码​

行内代码格式主要用于显示技术信息，如 URL。常见示例：

  • 文件名和路径（如 C:/User/[your_name]/AppData....test.png）
  • URL（如 https://zap-hosting.com）
  • 端口（如 :30120）
  • 命令（如 ipconfig）
  • SQL 查询（如 SELECT * FROM servers）
  • 快捷键（如 ENTER 或 CTRL + C）

表格​

表格适合展示大量重复信息，例如游戏中的命令、描述和用法。示例：

| 命令       | 描述                   | 用法                  |
| ----------- | ---------------------- | --------------------- |
| /help       | 发送帮助命令           | /help [category]      |
| /stop       | 停止服务器             | /stop [true/false]    |

代码块​

代码块适合展示命令、脚本、终端输出等内容。

使用三个反引号包裹代码块。可在第一个反引号后指定语言以高亮语法。示例（JavaScript）：

function hello(name) {
    console.log(name)
}

var server = "ZAP-Hosting"
hello(server)

警示框的使用​

你可以使用警示框突出显示特定信息，支持以下5种类型，语法相同，只需替换关键词。示例：

:::note
这是一个备注！替换上方关键词可更改类型。
:::

备注​

备注标题（可选）

用于显示额外但非关键的备注信息。

提示​

提示标题（可选）

放置你基于经验的实用小贴士。

信息​

信息标题（可选）

放置用户应知的重要信息。

注意​

注意标题（可选）

提醒用户在执行指南时需谨慎的事项。

危险​

危险标题（可选）

用于强调关键警告，特别是已知漏洞或废弃功能。

截图​

截图是引导读者视觉跟随步骤的极佳方式，建议适当使用。

为兼顾德语区，截图时请同时提供英文版和德文版，确保截图内容一致。可将两者并排放置。德文截图会在 ZAP-Docs 团队翻译后替换使用。

添加截图语法示例，替换 your_url 为图片链接：

![](your_url)

最佳做法是使用 Imgur 等图床上传图片，或者在 GitHub 网站编辑时直接拖拽图片自动上传。

术语​

文档中会使用大量关键术语。为确保所有文章一致，我们统一使用美式英语拼写。以下是一些常用术语的标准化说明。

ZAP-Hosting 产品​

引用 ZAP-Hosting 产品时，务必确保名称、拼写和大小写正确。可访问ZAP-Hosting 官网查看相关产品页面的官方写法。

用户自定义属性​

大多数指南中，配置项如用户、主机名、域名、IP 地址和 URL 等需读者替换为自己的信息。

默认应使用 [your_attribute] 格式区分静态元素和用户自定义元素，其中 attribute 替换为具体属性类型。例如，提及 IP 时写 [your_server_ip]，提及 URL 时写 http://[your_server_ip]:30120。首次出现时应说明哪些属性需替换，确保读者理解。

默认主机名、用户名或数据库名使用 zaphosting。

软件​

提及软件时，确保名称拼写和大小写正确。如果软件官网大小写不统一，文章内保持一致即可。

首次提及软件时应链接到其官网（如有官方站点）。

编辑此页
最后由 Florian Galz 于 更新
Cookie 设置