格式指南

目录

标题和副标题

读者会对标题、无序列表和链接给予更多关注，因此务必确保这些项目的前两三个词尽可能地“前置”信息。

最佳实践

  • 标题和副标题应让读者知道页面中会提供什么内容。
  • 它们应简洁准确地描述内容的主题。
  • 标题应简短（不超过八个词），直击要点，并使用简单、主动的语言撰写。
  • 应避免双关语、诱导性内容和文化引用。
  • 跳过冠词（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 个空格。
  • 忽略代码时使用三个点 ( ... )。

标注

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

最佳实践

  • 将 Warning、Important 或 Note 这些词语设为粗体。不要将标注内的内容设为粗体。
  • 最好避免在同一页面上放置过多的文本标注。过度使用可能会使页面显得杂乱，并削弱其效果。
文本标注用例场景颜色或标注框
警告使用 Warning 标签向读者指示哪些操作可能导致硬件或软件损坏、数据丢失。红色
✅ 示例：警告：使用 docker login 命令时，您的凭据会存储在主目录的 .docker/config.json 文件中。密码在此文件中经过 base64 编码。
重要使用 Important 标签向读者指示哪些操作可能导致程度较低的问题。黄色
✅ 示例：更新 Docker Desktop 条款
注意使用 Note 标签用于可能不适用于所有读者的信息，或者信息与主题相关但非核心。蓝色
✅ 示例：删除仓库会删除其中包含的所有镜像及其构建设置。此操作无法撤销。

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

记录如何通过 Docker Desktop 或 Docker Hub UI 进行导航时

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

可选步骤

如果步骤是可选的，请以“可选.”（Optional.）开头。

例如

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

占位符文本

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

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

docker extension install <name-of-your-extension>

表格

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

注意，在许多情况下，无序列表足以描述每项具有简单描述的列表。但是，如果数据最适合用矩阵描述，则表格是最佳选择。

最佳实践

  • 表格标题使用句子大小写（即首字母大写，其余小写）。
  • 为了使表格易于访问和扫描，表格不应有空单元格。如果单元格没有其他有意义的值，请考虑输入 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 |
页面选项