编写 Docker 使用指南的准则

目录

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

我们的文档使用 Markdown 编写，并使用 YAML 前置 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/

/.md` 下创建指南页面。元数据 位于 `_index.md` 页面上（您不需要为各个页面分配元数据）。

针对特定框架或语言的指南

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

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

用例指南

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

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

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

示例代码

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

在官方示例命名空间中托管示例还有助于确保阅读指南的用户的信任。

在 `dockersamples` 下发布代码库

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

写作风格

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

语气和语调

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

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

格式约定

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

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

最佳实践

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

其他资源

提交流程

  • 提案

    • 在Docker文档GitHub仓库提交一个添加新指南的请求。

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

      注意

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

  • 审核

    • 校对您的指南，确保其语法、清晰度和对指南的遵守情况。
    • 准备好草稿后，提交一个拉取请求，并附上原始问题的引用。
    • Docker文档团队和主题专家将审核您的提交，并直接在拉取请求中提供反馈。

  • 发布

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

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