撰写 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 *（可选）：涵盖的领域或主题。
  • params
    • time（可选）：预计阅读或完成时间。

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

文档结构

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

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

如果您要创建单页指南，请在 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 与特定框架或编程语言一起使用的指南，请考虑以下大纲

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

用例指南

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

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

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

示例代码

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

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

在 dockersamples 下发布仓库

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

写作风格

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

语气和语调

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

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

格式化约定

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

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

最佳实践

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

其他资源

提交流程

  • 提案

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

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

      注意

      避免从您 fork 的 main 分支贡献，因为这会使维护人员更难帮助您修复可能出现的任何问题。

  • 审阅

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

  • 发布

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

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

页面选项