編寫 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 與特定框架或程式語言一起使用的指南，請考慮以下大綱：

  1. 簡介
    • 簡要介紹 Docker 上下文中的框架或語言。
    • 解釋使用者透過本指南將實現的目標。
    • 列出所需的軟體、工具和知識。
  2. 開發環境設定
    • 指導使用者設定開發環境。
    • 包括編寫或獲取示例程式碼的說明。
    • 展示如何執行容器進行本地開發。
  3. 構建應用程式
    • 解釋如何建立適合應用程式的 Dockerfile。
    • 提供構建 Docker 映象的分步說明。
    • 如果適用，展示如何使用 Docker 測試應用程式。
  4. 使用 Docker 部署
    • 展示如何在 Docker 容器中執行應用程式。
    • 討論配置選項和最佳實踐。
  5. 最佳實踐和結論
    • 提供最佳化 Docker 與框架或語言一起使用的技巧。
    • 總結關鍵要點，建議下一步驟和進一步閱讀。

用例指南

對於專注於使用 Docker 實現特定目標或用例（例如，部署機器學習模型）的指南，請使用靈活的大綱以確保邏輯流程。

以下大綱是一個示例。結構應根據內容進行調整，以確保清晰、邏輯的進展。根據您的用例指南的主題，具體結構將有所不同。

  1. 簡介
    • 描述問題或目標。
    • 解釋在這種情況下使用 Docker 的好處。
  2. 先決條件
    • 列出所需的工具、技術和先驗知識。
  3. 設定
    • 提供設定環境的說明。
    • 包括任何必要的配置步驟。
  4. 實施
    • 逐步講解過程。
    • 使用程式碼片段和解釋來說明關鍵點。
  5. 執行或部署應用程式
    • 指導使用者如何執行或部署解決方案。
    • 討論任何驗證步驟以確保成功。
  6. 結論
    • 回顧已實現的目標。
    • 建議進一步閱讀或高階主題。

示例程式碼

如果您建立了一個帶有原始碼的示例倉庫來配合您的指南，我們強烈建議您在 GitHub 的 dockersamples 組織下發布該倉庫。在 Docker 示例組織下（而不是您的個人帳戶下）釋出您的原始碼可確保原始碼在釋出後仍可供文件站點的維護者訪問。萬一指南中出現錯誤或問題，文件團隊可以更輕鬆地更新指南及其相應的示例倉庫。

將示例託管在官方示例名稱空間中也有助於獲得閱讀指南的使用者的信任。

在 dockersamples 下發布倉庫

要在 dockersamples 組織下發布您的倉庫，請使用 dockersamples 模板在您的個人名稱空間下啟動一個示例倉庫。完成內容草稿並提交文件的拉取請求後，我們可以將倉庫轉移到 dockersamples 組織。

寫作風格

所有標題都使用句子大小寫。這意味著只有第一個單詞和專有名詞首字母大寫。

語氣和語調

  • 清晰簡潔：使用簡單的語言和簡短的句子有效地傳達資訊。
  • 主動語態：使用主動語態吸引讀者（例如，“執行命令”而不是“應該執行命令”）。
  • 一致性：在整個指南中保持一致的語氣和術語。

有關詳細準則，請參閱我們的語氣和語調文件。

格式約定

  • 標題：主要部分使用 H2，子部分使用 H3，均採用句子大小寫。
  • 程式碼示例：提供完整、可工作的程式碼片段，並帶有語法高亮。
  • 列表和步驟：順序步驟使用編號列表，非順序資訊使用專案符號。
  • 強調：UI 元素使用粗體（例如，按鈕），強調使用斜體。
  • 連結：使用描述性連結文字（例如，安裝 Docker）。

有關更多詳細資訊，請參閱我們的內容格式指南和語法和風格規則。

最佳實踐

  • 測試所有說明
    • 確保所有程式碼和命令按預期工作。
    • 驗證指南可以從頭到尾成功遵循。
  • 相關性
    • 關注實際應用和場景。
    • 使內容與最新的 Docker 版本保持同步。
  • 故障排除技巧
    • 預測常見問題並提供解決方案或參考。
  • 視覺輔助
    • 在有助於理解的地方包含螢幕截圖或圖表。
    • 新增標題和替代文字以方便訪問。
  • 第三方工具
    • 避免要求使用者安裝第三方工具或修改其本地開發環境。
    • 在適用情況下優先使用容器化工具和方法（例如 docker exec）。
    • 某些工具被合理地假定已安裝或作為指南的先決條件，例如 Node.js 和 npm。請自行判斷。

其他資源

提交流程

  • 提案

    • 在Docker 文件 GitHub 倉庫上提出一個問題，請求新增新指南。

    • 提案被接受後，透過分叉倉庫併為您的工作建立一個分支來開始編寫指南。

      注意

      避免從您分支的 main 分支進行貢獻，因為它會使維護者更難幫助您解決可能出現的任何問題。

  • 審閱

    • 校對您的指南，檢查語法、清晰度和是否符合準則。
    • 當您的草稿準備就緒時，提交拉取請求，並引用原始問題。
    • Docker 文件團隊和主題專家將審閱您的提交併直接在拉取請求上提供反饋。

  • 釋出

    • 當審閱者批准併合並您的拉取請求後，您的指南將釋出在 Docker 文件網站上。

感謝您為 Docker 社群做出的貢獻。您的專業知識幫助全球使用者駕馭 Docker 的強大功能。