编写 Docker 使用指南的规范

Table of contents

本指南提供了编写教程式使用指南的说明和最佳实践，旨在帮助用户使用 Docker 实现特定目标。这些指南将与我们的产品手册和参考资料一起，发布在网站的 指南部分。

我们的文档使用 Markdown 编写，并使用 YAML front matter 来存储元数据。我们使用 Hugo 来构建网站。有关如何为 Docker 文档编写内容的更多信息，请参阅我们的 CONTRIBUTING.md。

指南的目的

我们的使用指南旨在：

  • 教导用户如何在各种情境下利用 Docker。
  • 通过分步教程提供实用的动手经验。
  • 帮助用户实现与其兴趣或项目相关的目标。

受众

  • 经验水平：从初学者到高级用户。
  • 角色：开发人员、系统管理员、DevOps 工程师等。
  • 技术：各种编程语言和框架。

指南的元数据

每篇指南必须在文档开头包含一个元数据部分。这些元数据有助于用户根据其兴趣和需求发现和筛选指南。

元数据格式示例 

---
title: 使用 Docker 部署机器学习模型
linkTitle: 用于机器学习部署的 Docker
description: 学习如何使用 Docker 容器化和部署机器学习模型。
summary: |
  本指南将引导您完成容器化机器学习模型并使用 Docker 进行部署的步骤，
  从而实现可扩展且可移植的 AI 解决方案。
tags: [machine-learning, deployment]
languages: [python]
params:
  time: 30 minutes
---

元数据字段

  • title（必需）：指南的主标题，使用句子大小写。
  • linkTitle（可选）：用于导航菜单的较短标题。
  • description（必需）：用于 SEO 的简明描述。
  • summary（必需）：指南内容的简要概述。
  • languages *（可选）：使用的编程语言列表。
  • tags *（可选）：涵盖的领域或主题领域。
  • params
    • time（可选）：预计阅读或完成时间。

* 必须至少应用 languages 或 tags 分类法之一。这些值用于将页面与指南登陆页面上的筛选选项相关联。

文档结构

我们的指南强调边做边学。根据指南的类型，其结构可能会有所不同，以最好地适应内容并提供流畅的学习体验。

所有指南都直接位于 Docker 文档仓库的 content/guides/ 目录下。指南可以是单页或多页。对于多页指南，每一页都是顺序工作流中的一个步骤。

如果您要创建单页指南，请在指南目录中创建一个 Markdown 文件：

# 创建文件
touch content/guides/my-docker-guide.md
# 或者如果您已安装 Hugo：
hugo new content/guides/my-docker-guide.md

要创建多页指南，请创建一个目录，其中每个页面都是一个 Markdown 文件，并使用 _index.md 文件表示指南的介绍。

# 为指南创建索引页
mkdir content/guides/my-docker-guide.md
touch content/guides/my-docker-guide/_index.md
# 或者如果您已安装 Hugo：
hugo new content/guides/my-docker-guide/_index.md

然后根据需要在 content/guides/<dir>/<page>.md 下创建指南的页面。元数据位于 _index.md 页面上（您无需为单个页面分配元数据）。

特定框架或语言的指南

对于演示如何将 Docker 与特定框架或编程语言结合使用的指南，请考虑以下大纲：

  1. 简介
    • 在 Docker 的背景下简要介绍该框架或语言。
    • 解释用户在本指南结束时将实现什么。
    • 列出所需的软件、工具和知识。
  2. 开发环境设置
    • 引导用户设置开发环境。
    • 包括编写或获取示例代码的说明。
    • 展示如何为本地开发运行容器。
  3. 构建应用程序
    • 解释如何为应用程序创建量身定制的 Dockerfile。
    • 提供构建 Docker 镜像的分步说明。
    • 如果适用，展示如何使用 Docker 测试应用程序。
  4. 使用 Docker 部署
    • 展示如何在 Docker 容器中运行应用程序。
    • 讨论配置选项和最佳实践。
  5. 最佳实践和结论
    • 提供针对该框架或语言优化 Docker 使用的技巧。
    • 总结关键要点，建议后续步骤和进一步阅读。

用例指南

对于专注于使用 Docker 完成特定目标或用例（例如，部署机器学习模型）的指南，请使用灵活的大纲以确保逻辑流程。

以下大纲是一个示例。应调整结构以最好地适应内容，并确保清晰、逻辑性的进展。根据您的用例指南的主题，确切的结构会有所不同。

  1. 简介
    • 描述问题或目标。
    • 解释在此情境下使用 Docker 的好处。
  2. 先决条件
    • 列出所需的工具、技术和先验知识。
  3. 设置
    • 提供设置环境的说明。
    • 包括任何必要的配置步骤。
  4. 实现
    • 逐步完成该过程。
    • 使用代码片段和解释来说明关键点。
  5. 运行或部署应用程序
    • 指导用户如何执行或部署解决方案。
    • 讨论任何验证步骤以确保成功。
  6. 结论
    • 回顾已实现的内容。
    • 建议进一步阅读或高级主题。

示例代码

如果您创建了一个示例代码仓库来配合您的指南，我们强烈建议您在 GitHub 的 dockersamples 组织下发布该仓库。将您的源代码发布在此组织下，而不是您的个人帐户下，可确保在发布后文档站点的维护者仍然可以访问源代码。如果指南中出现错误或问题，文档团队可以更轻松地更新指南及其相应的示例仓库。

将示例托管在官方示例命名空间中也有助于与阅读指南的用户建立信任。

在 dockersamples 下发布仓库

要将您的仓库发布在 dockersamples 组织下，请使用 dockersamples 模板 在您的个人命名空间下启动一个示例仓库。当您完成内容起草并为文档打开拉取请求后，我们可以将仓库转移到 dockersamples 组织。

写作风格

所有标题和标题都使用 句子大小写。这意味着只有第一个单词和专有名词大写。

语气和语调

  • 清晰简洁：使用简单的语言和短句来有效地传达信息。
  • 主动语态：使用主动语态写作以吸引读者（例如，“运行命令”而不是“应该运行命令”）。
  • 一致性：在整个指南中保持一致的语气和术语。

有关详细指南，请参阅我们的 语气和语调文档。

格式约定

  • 标题：主要部分使用 H2，子部分使用 H3，并遵循句子大小写。
  • 代码示例：提供完整、可工作的代码片段，并带有语法高亮。
  • 列表和步骤：对于顺序步骤使用编号列表，对于非顺序信息使用项目符号。
  • 强调：对 UI 元素使用粗体（例如，按钮），对强调内容使用斜体。
  • 链接：使用描述性链接文本（例如， 安装 Docker）。

更多详情，请参阅我们的 内容格式指南和 语法和风格规则。

最佳实践

  • 测试所有说明
    • 确保所有代码和命令按预期工作。
    • 验证指南是否可以从头到尾成功遵循。
  • 相关性
    • 专注于实际应用和场景。
    • 保持内容与最新 Docker 版本同步。
  • 故障排除技巧
    • 预测常见问题并提供解决方案或参考。
  • 视觉辅助
    • 在增强理解的地方包含截图或图表。
    • 添加标题和替代文本以提高可访问性。
  • 第三方工具
    • 避免要求用户安装第三方工具或修改其本地开发环境。
    • 在适用的情况下，优先使用容器化工具和方法（例如 docker exec）。
    • 可以合理地假定某些工具已安装或作为指南的先决条件，例如 Node.js 和 npm。请运用您的判断力。

其他资源

提交流程

  • 提案

    • 在 Docker 文档 GitHub 仓库 上提出一个 issue，请求添加新指南。

    • 一旦提案被接受，通过 fork 仓库并为您的工作创建一个分支来开始编写您的指南。

      Note

      避免从您 fork 的 main 分支进行贡献，因为这会使维护者更难帮助您解决可能出现的任何问题。

  • 审查

    • 校对您的指南，检查语法、清晰度以及是否符合指南。
    • 一旦您的草稿准备就绪，发起一个拉取请求，并引用原始 issue。
    • Docker 文档团队和主题专家将审查您的提交，并直接在拉取请求上提供反馈。

  • 发布

    • 当审查者批准并合并您的拉取请求后，您的指南将在 Docker 文档网站上发布。

感谢您为 Docker 社区做出贡献。您的专业知识帮助全世界的用户利用 Docker 的强大功能。