撰寫 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/` 目錄下。指南可以是單頁或多頁。如果是多頁指南，則每一頁都是循序工作流程中的一個步驟。

如果您要建立單頁指南，請在指南目錄中建立單個 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. 結論
    • 回顧已達成的目標
    • 建議進一步閱讀或進階主題

程式碼範例

如果您建立了包含程式碼範例的儲存庫來搭配您的指南，我們強烈建議您在 GitHub 上的 dockersamples 組織下發布該儲存庫。在這個組織下發布您的原始程式碼，而不是在您的個人帳戶下發布，可確保文件網站的維護人員在發布後仍可存取原始程式碼。如果指南中出現錯誤或問題，文件團隊可以更輕鬆地更新指南及其對應的範例儲存庫。

在官方範例命名空間中託管範例也有助於確保閱讀指南的使用者信任。

在 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 的力量。