撰写 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 与特定框架或编程语言一起使用的指南,请考虑以下大纲
- 引言
- 在 Docker 环境中简要介绍框架或语言。
- 解释用户通过本指南结束时将实现什么。
- 列出所需的软件、工具和知识。
- 开发环境设置
- 指导用户设置开发环境。
- 包含编写或获取示例代码的说明。
- 展示如何在本地开发中运行容器。
- 构建应用程序
- 解释如何创建适合应用程序的 Dockerfile。
- 提供构建 Docker 镜像的分步说明。
- 如果适用,展示如何使用 Docker 测试应用程序。
- 使用 Docker 部署
- 展示如何在 Docker 容器中运行应用程序。
- 讨论配置选项和最佳实践。
- 最佳实践和结论
- 提供与该框架或语言一起优化 Docker 使用的技巧。
- 总结要点,建议后续步骤和进一步阅读。
用例指南
对于侧重于使用 Docker 完成特定目标或用例(例如,部署机器学习模型)的指南,请使用灵活的大纲以确保逻辑流畅。
以下大纲是一个示例。应调整结构以最适合内容并确保清晰、逻辑的进展。根据您的用例指南的主题,具体结构会有所不同。
- 引言
- 描述问题或目标。
- 解释在此场景中使用 Docker 的好处。
- 先决条件
- 列出所需的工具、技术和先前知识。
- 设置
- 提供设置环境的说明。
- 包含任何必要的配置步骤。
- 实现
- 循序渐进地讲解整个过程。
- 使用代码片段和解释来说明要点。
- 运行或部署应用程序
- 指导用户如何执行或部署解决方案。
- 讨论任何确保成功的验证步骤。
- 结论
- 回顾所实现的内容。
- 建议进一步阅读或高级主题。
示例代码
如果您创建了一个包含源代码的示例仓库来配合您的指南,我们强烈建议您将该仓库发布到 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 的强大功能。