格式指南

目录

标题和副标题

读者会稍微多关注标题、项目符号列表和链接，因此务必确保这些项目的前两到三个词尽可能多地“提前加载”信息。

最佳实践

  • 标题和副标题应让读者知道他们在页面上会找到什么。
  • 它们应该简洁准确地描述内容的主题。
  • 标题应简短（不超过八个字），切中要点，并使用简洁、主动的语言书写。
  • 应避免使用双关语、预告和文化参考。
  • 跳过引导词（a、the 等）。

页面标题

页面标题应以行动为导向。例如：- 启用 SCIM - 安装 Docker Desktop

最佳实践

  • 确保页面标题和目录 (TOC) 条目匹配。
  • 如果要在目录 (_toc.yaml) 中的页面标题中使用“：”，则必须将整个标题用“”括起来，以避免破坏构建。
  • 如果向 TOC 文件添加新条目，请确保其以尾部斜杠 (/) 结尾。如果不这样做，页面将不会显示侧边导航。

图片

包括屏幕截图在内的图片可以帮助读者更好地理解概念。但是，应谨慎使用它们，因为它们往往会过时。

最佳实践

  • 拍摄屏幕截图时
    • 不要使用 Lorem ipsum 文本。尝试复制某人在现实场景中如何使用该功能，并使用真实的文本。
    • 仅捕获相关的 UI。不要包含不必要的空白或无助于说明要点的 UI 区域。
    • 保持小巧。如果不需要显示屏幕的全部宽度，则不要显示。
    • 查看图片在页面上的渲染效果。确保图片不模糊或过于醒目。
    • 保持一致性。协调屏幕截图与文档页面上已有的其他屏幕截图，以获得一致的阅读体验。
    • 为了使 Git 存储库轻量化，请压缩（无损）图像。请务必在将图像添加到存储库之前压缩它们。在将图像添加到存储库后压缩图像实际上会加剧对 Git 存储库的影响（但是，它仍然会优化浏览期间的带宽）。
    • 不要忘记从不再使用的存储库中删除图像。

有关如何将图像添加到内容的信息，请参阅 有用的组件和格式示例。

注意不要创建过多的链接，尤其是在正文中。过多的链接可能会分散注意力或将读者从当前页面带走。

当人们点击链接时，他们经常会失去思路，并且无法返回到原始页面，即使他们还没有吸收其中包含的所有信息。

最好的链接为读者提供了另一种扫描信息的方式。

最佳实践

  • 使用不会误导或承诺过多的简洁语言。
  • 简洁明了（大约五个字是最好的）。
  • 允许人们预测（以相当大的信心）如果他们选择链接会得到什么。尽可能在链接中反映目标页面的标题文本。
  • 在链接的开头提前加载面向用户和行动的术语（下载我们的应用程序）。
  • 避免使用通用的号召性用语（例如点击此处，了解更多信息）。
  • 超链接文本时，不要包含任何结尾标点符号（例如句点、问号或感叹号）。
  • 除非链接文本在普通正文中也是斜体或粗体，否则不要将链接文本设置为斜体或粗体。

有关如何将链接添加到内容的信息，请参阅 有用的组件和格式示例。

代码和代码示例

将以下内容格式化为代码：Docker 命令、指令和文件名（包名称）。

要应用内联代码样式，请将文本用单个反引号 (`) 括起来。

有关如何将代码块添加到内容的信息，请参阅 有用的组件和格式示例。

命令的最佳实践

  • 命令提示符和 Shell
    • 对于非特权 Shell，请在代码块中的命令前加上 $ 提示符符号。
    • 对于特权 Shell，请在代码块中的命令前加上 # 提示符符号。
    • 对于远程 Shell，请添加远程计算机的上下文并排除路径。例如，user@host $。
    • 添加任何特定于 Windows 的命令时，请指定 Windows Shell（命令提示符、PowerShell 或 Git Bash）。无需为每个 Windows Shell 包含命令。
    • 为多个操作系统或 Shell 添加命令时，请使用选项卡。有关如何将选项卡添加到内容的信息，请参阅 选项卡。
  • 用户将复制和运行的命令
    • 如果命令产生输出或要求用户验证结果，则每个代码块添加一个命令。
    • 将命令输出添加到与命令分开的代码块中。
  • 用户不会复制和运行的命令
    • 使用 POSIX 兼容语法。无需包含 Windows 语法。
    • 将可选参数用方括号 ( [ ] ) 括起来。
    • 在互斥参数之间使用管道 ( | )。
    • 在重复的参数后使用三个点 ( ... )。

代码的最佳实践

  • 将代码块嵌套在列表项下时，缩进代码块 3 个空格。
  • 省略代码时，使用三个点 ( ... )。

标注

使用标注来强调页面上的选定信息。

最佳实践

  • 将“警告”、“重要”或“注意”一词格式化为粗体。不要将标注中的内容加粗。
  • 最好避免在一个页面上放置大量文本标注。如果过度使用，它们会使外观杂乱无章，并会削弱其影响。
文本标注用例场景颜色或标注框
警告使用警告标签向读者发出信号，说明某些操作可能会损坏硬件或导致软件数据丢失。红色
✅ 示例：警告：使用 `docker login` 命令时，您的凭据将存储在您主目录中的 `.docker/config.json` 中。此文件中的密码是 base64 编码的。
重要使用“重要”标签向读者发出信号，说明某些操作可能会导致较小程度的问题。黄色
✅ 示例：Docker Desktop 条款更新
注意将“注意”标签用于可能不适用于所有读者的信息，或者如果信息与主题无关。蓝色
✅ 示例：删除存储库会删除它包含的所有镜像及其构建设置。此操作无法撤消。

有关如何将标注添加到内容的信息，请参阅 有用的组件和格式示例。

记录如何浏览 Docker Desktop 或 Docker Hub UI 时

  • 始终先使用位置，然后使用操作。例如：*从**可见性**下拉列表（位置）中选择公共（操作）。*
  • 简洁具体。例如：执行：*选择**保存**。* 不执行：*选择**保存**以使更改生效。*
  • 如果步骤必须包含原因，则从原因开始该步骤。这有助于用户更快地扫描。执行：*要查看更改，请在合并请求中选择链接。* 不执行：*选择合并请求中的链接以查看更改*

可选步骤

如果步骤是可选的，则从“可选”一词开始，后跟句点。

例如

1. 可选。输入作业说明。

占位符文本

您可能希望提供使用特定值的命令或配置。

在这些情况下，使用 < 和 > 来标注读者需要用自己的值替换文本的位置。例如

docker extension install <你的扩展名>

表格

使用表格以简洁明了的方式描述复杂信息。

请注意，在许多情况下，无序列表足以描述项目列表，每个项目只有一个简单的描述。但是，如果你的数据最适合用矩阵来描述，那么表格是最佳选择。

最佳实践

  • 表格标题使用首字母大写形式。
  • 为确保表格易于访问和浏览，表格不应包含任何空单元格。如果单元格没有其他有意义的值，请考虑输入“N/A”（表示“不适用”）或“None”。

有关如何向内容中添加表格的信息，请参阅 有用的组件和格式示例。

引用文件类型

讨论文件类型时，请使用该类型的正式名称。不要使用文件名扩展名来泛指文件类型。

| Correct | Incorrect |
| --- | --- |
| a PNG file | a .png file |
| a Bash file | an .sh file |

引用单位

提及计量单位时，请使用全大写的缩写形式，并在值和单位之间留一个空格。例如

| Correct | Incorrect |
| --- | --- |
| 10 GB | 10GB |
| 10 GB | 10 gb |
| 10 GB | 10 gigabytes |