跳到主要内容

指南规范

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 章节进一步拆分成更小的部分。

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

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

标题​

标题应简洁明了，清晰反映指南的主要目标。考虑读者完成后能达成什么，比如完成安装、配置服务或理解某个技术主题。标题应能让读者一眼看出成果。

每个标题必须以对应产品类别前缀开头。该前缀应与侧边栏中指南所在的分类一致。查看同类别已有指南有助于保持命名规范。

例如，涉及 VPS 产品的指南应遵循类似格式：VPS: SteamCMD Linux 设置。

如果指南是通用的，适用于多个产品，比如同时适用于 VPS 和独立服务器的服务或游戏服务器安装，则标题中不应包含产品名称。这类指南是产品无关的，因此不需要特定产品前缀。

介绍​

指南的介绍应简短明了，通常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)

警示框（Admonitions）​

警示框用于突出指南中的重要信息。共有五种类型，每种用途不同。

使用时必须定义清晰且描述性的标题，确保读者无需阅读全文即可理解重点。

语法统一，仅关键词不同：

:::warning[标题]
	内容
:::

注意​

示例：附加信息

用于补充信息，帮助读者但非完成指南必需。

提示​

示例：性能优化提示

分享实用建议、最佳实践或效率提升技巧。

信息​

示例：要求或重要细节

提供读者在操作前或过程中应知的重要背景信息。

警告​

示例：配置风险

提醒读者可能出现的问题或错误。

危险​

示例：已知漏洞或弃用功能

用于严重警告，包括已知漏洞、不可逆操作、安全风险或弃用功能。

截图​

截图是引导读者视觉跟随步骤的极佳方式，建议适当使用。请确保截图中的内容为英文，因为文档以英文编写，且其他语言版本会使用相同英文截图。截图分辨率应足够大，确保所有元素清晰可见，避免过小或裁剪过度。

添加截图语法示例，替换 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 设置