格式指南

标题和副标题

读者更多地关注标题、项目符号列表和链接，因此确保这些项目中的前两到三个单词尽可能“前置”信息非常重要。

最佳实践

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

页面标题

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

最佳实践

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

图片

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

最佳实践

  • 当您截屏时：
    • 不要使用 lorem ipsum 文本。尝试复制某人在现实场景中如何使用该功能，并使用真实的文本。
    • 仅捕获相关 UI。不要包含不必要的空白或无助于说明要点的 UI 区域。
    • 保持较小。如果您不需要显示屏幕的整个宽度，请不要显示。
    • 查看图像在页面上的呈现方式。确保图像不模糊或不清晰。
    • 始终如一。将屏幕截图与文档页面上已有的其他屏幕截图进行协调，以获得一致的阅读体验。
    • 要保持 Git 存储库轻量，请压缩图像（无损）。在将图像添加到存储库之前，请务必先对其进行压缩。将图像添加到存储库后对其进行压缩实际上会恶化对 Git 存储库的影响（但是，它仍然优化了浏览时的带宽）。
    • 不要忘记从存储库中删除不再使用的图像。

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

请注意不要创建太多链接，尤其是在正文中。过多的链接可能会分散读者的注意力或使他们离开当前页面。

当人们点击链接时，他们常常会失go思路，无法返回到原始页面，尽管他们没有吸收其中包含的所有信息。

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

最佳实践

  • 使用简单的语言，不要误导或承诺太多。
  • 简短且具有描述性（最好是五个字左右）。
  • 允许人们（以相当的置信度）预测如果选择链接他们会得到什么。尽可能在链接中镜像目标页面上的标题文本。
  • 在链接的开头预先加载面向用户和操作的术语（下载我们的应用程序）。
  • 避免通用的号召性用语（例如单击此处，了解更多）。
  • 超链接文本时请勿包含任何结尾标点符号（例如句点、问号或感叹号）。
  • 不要将链接文本设置为斜体或粗体，除非它与正常的正文副本一样。

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

代码和代码示例

将以下内容格式化为代码：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 <name-of-your-extension>

表格

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

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

最佳实践

  • 表格标题使用句首字母大写。
  • 为了保持表格可访问和可扫描，表格不应包含任何空单元格。如果单元格没有其他有意义的值，请考虑输入“N/A”表示“不适用”或“无”。

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

参考文件类型

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

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