格式化指南

标题和副标题

读者对标题、项目符号列表和链接的关注度略高，因此务必确保这些项目的前两到三个词尽可能“前置”信息。

最佳实践

标题和副标题应让读者知道他们将在页面上找到什么。
它们应简洁准确地描述内容。
标题应简短（不超过八个词），切中要点，并使用清晰、主动的语言书写。
您应避免使用双关语、诱导性内容和文化典故。
跳过冠词（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 用户界面时

始终使用位置，然后是动作。例如：从可见性下拉列表（位置）中，选择“公共”（动作）。
简明扼要。例如：正确：选择保存。 错误：选择保存以使更改生效。
如果某个步骤必须包含原因，请以原因开头。这有助于用户更快地浏览。正确：要查看更改，请在合并请求中选择链接。 错误：在合并请求中选择链接以查看更改。

可选步骤

如果某个步骤是可选的，请以单词“可选”开头，后跟句点。

例如：

1. 可选。输入作业描述。

占位符文本

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

在这些情况下，请使用 < 和 > 来指示读者必须将文本替换为自己的值。例如

docker extension install <您的扩展名称>

表格

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

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

最佳实践

表格标题使用句子大小写。
为了保持表格的可访问性和可扫描性，表格不应有任何空单元格。如果某个单元格没有其他有意义的值，请考虑输入“不适用”的 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 |