编写 Docker 使用指南的准则

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

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

指南目的

我们的使用指南旨在：

教育用户如何在各种上下文中使用 Docker。
通过分步教程提供实用的动手经验。
帮助用户实现与其兴趣或项目相关的特定目标。

受众

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

指南元数据

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

元数据格式示例

---
title: Deploy a machine learning model with Docker
linkTitle: Docker for ML deployment
description: Learn how to containerize and deploy a machine learning model using Docker.
summary: |
  This guide walks you through the steps to containerize a machine learning
  model and deploy it using Docker, enabling scalable and portable AI
  solutions.
tags: [machine-learning, deployment]
languages: [python]
params:
  time: 30 minutes
---

元数据字段

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

* 请至少应用一个 languages 或 tags 分类。这些值用于将页面与指南着陆页上的筛选选项关联起来。

文档结构

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

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

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

# Create the file
touch content/guides/my-docker-guide.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide.md

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

# Create the index page for the guide
mkdir content/guides/my-docker-guide.md
touch content/guides/my-docker-guide/_index.md
# or if you have Hugo installed:
hugo new content/guides/my-docker-guide/_index.md

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

特定框架或语言的指南

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

简介
- 简要介绍 Docker 上下文中的框架或语言。
- 解释用户通过本指南将实现的目标。
- 列出所需的软件、工具和知识。
开发环境设置
- 指导用户设置开发环境。
- 包括编写或获取示例代码的说明。
- 展示如何运行容器进行本地开发。
构建应用程序
- 解释如何创建适合应用程序的 Dockerfile。
- 提供构建 Docker 镜像的分步说明。
- 如果适用，展示如何使用 Docker 测试应用程序。
使用 Docker 部署
- 展示如何在 Docker 容器中运行应用程序。
- 讨论配置选项和最佳实践。
最佳实践和结论
- 提供优化 Docker 与框架或语言一起使用的技巧。
- 总结关键要点，建议下一步骤和进一步阅读。

用例指南

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

以下大纲是一个示例。结构应根据内容进行调整，以确保清晰、逻辑的进展。根据您的用例指南的主题，具体结构将有所不同。

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

示例代码

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

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

在 `dockersamples` 下发布仓库

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

写作风格

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

语气和语调

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

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

格式约定

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

有关更多详细信息，请参阅我们的内容格式指南和语法和风格规则。

最佳实践

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

其他资源

现有指南
- 请参阅Docker 指南以获取示例和灵感。
风格指南

提交流程

提案
- 在Docker 文档 GitHub 仓库上提出一个问题，请求添加新指南。
- 提案被接受后，通过分叉仓库并为您的工作创建一个分支来开始编写指南。
  注意
  避免从您分支的 main 分支进行贡献，因为它会使维护者更难帮助您解决可能出现的任何问题。
审阅
- 校对您的指南，检查语法、清晰度和是否符合准则。
- 当您的草稿准备就绪时，提交拉取请求，并引用原始问题。
- Docker 文档团队和主题专家将审阅您的提交并直接在拉取请求上提供反馈。
发布
- 当审阅者批准并合并您的拉取请求后，您的指南将发布在 Docker 文档网站上。

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