撰寫 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 的強大功能。

頁面選項