跳到主要内容

指南规范

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 设置

介绍​

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

警示框的使用​

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

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

注释​

注释标题（可选）

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

提示​

提示标题（可选）

放置你基于经验的提示。

信息​

信息标题（可选）

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

注意​

注意标题（可选）

提醒用户在跟随指南时需谨慎的事项。

危险​

危险标题（可选）

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

截图​

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

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