教學課程：格式指南

請參考下列指南，以教學課程的形式呈現內容，協助使用者有效熟悉專案。

Cloud Shell 功能

  • 獨特版面配置：教學課程會顯示在 Google Cloud 控制台右側的側邊面板中。
  • 導覽：使用者可以在每個步驟中，使用「下一步」和「上一步」按鈕瀏覽教學課程。他們也可以關閉教學課程，並從上次中斷的地方繼續。
  • 程式碼：程式碼片段可直接複製到 Cloud Shell。

含有已啟用教學課程的Google Cloud 控制台工作階段

Cloud Shell 編輯器工作階段，並開啟教學課程窗格。使用者只要按一下按鈕，即可將程式碼直接複製到 Cloud Shell，並透過「下一步」和「上一步」按鈕在頁面之間移動。

寫作風格

  • 保持輕鬆：教學課程的基調應具資訊性且有幫助，但不要過於正式。
  • 以第二人稱代名詞稱呼使用者：使用第二人稱代名詞 (請使用：您、您的；請勿使用：我們、我、我們的等)。
  • 說明原因和影響：要求使用者執行步驟時，請說明該動作背後的理由和預期結果。
  • 設定明確目標：撰寫教學課程內容前，請先為使用者設定明確的目標。製作教學課程時，請牢記這個目標。
原始版本 修訂後的版本 改善方法
下一頁將說明如何建立新教學課程。 繼續下一個步驟，開始設定教學課程。 以使用者為主；使用主動語態

使用輕鬆的語言
執行下列指令：

``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ```

如要顯示列出所有專案和其 ID 號碼，且標題為「Projects」的清單，請執行下列指令： ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` 清楚說明預期的輸出結果
Let's get started! Let's get started!

本指南將說明如何建構自己的互動式教學課程。本教學課程也會逐步說明如何產生按鈕，供使用者啟動完成的教學課程。

清楚呈現教學課程的內容藍圖

撰寫內容時，請務必以這個重點為中心！

最佳做法

  • 保持簡潔：教學課程特有的空間限制，讓您一次只能為使用者顯示數量有限的資訊。請避免使用難以掃描且需要上下捲動的大塊文字；最好以小區塊的文字來呈現資訊。

    • 以每頁不超過 5 個步驟和 3 個程式碼片段為原則。

    • 段落最好不要超過 5 行，且應只處理單一概念。

    • 如果網頁必須很長，請盡量將長度控制在窗格長度的兩倍以內。

    • 程式碼和終端區塊應小而易讀：

      • 以不超過 10 行為原則。
      • 每行最多 80 個半形字元，以減少水平捲動。
      • 避免程式碼區塊中出現多個指令，以免使用者必須執行大量的複製作業。

  • 介紹頁面：教學課程的開頭應先做一些簡單的介紹。

    • 設定期望：簡要說明使用者在完成教學課程後將獲得哪些益處。
    • 預計完成時間：粗略估計使用者完成教學課程所需的時間。編寫的教學課程應以 15 分鐘內可完成為原則。如果教學課程較為冗長 (或包含超過 15 個文字密集的頁面)，請考慮將其編成一系列篇章較短的教學課程。
    • 預先準備：清楚說明為了順利完成教學課程，使用者必須具備哪些資源或存取權限。
    範例

    ## 讓我們開始吧！

    加入互動式教學課程，協助使用者快速上手專案。

    本指南將為您示範如何建構自己的互動式教學課程 (如同本教學課程)。此外，本教學課程也會逐步說明如何產生按鈕，供使用者啟動完成的教學課程。

    **完成時間**：大約 10 分鐘

    **必要條件**：Cloud Billing 帳戶

    按一下「繼續」按鈕，前往下一個步驟。

  • 背景頁面

    • 設定場景：在編寫教學課程時加入一些背景資訊，通常會很有幫助。這類的背景資訊包括提供簡要的產品概述，或是簡短介紹 UI 的顯著特色。
    範例

    ## 什麼是 Cloud Shell？

    開始之前，我們先簡單瞭解 Cloud Shell 的功能。

    Cloud Shell 是個人專用的代管虛擬機器，預先載入 Google Cloud 產品的開發人員工具。這個互動式殼層環境內建程式碼編輯器、持續性磁碟儲存空間和網頁預覽功能。如要單獨使用指令列存取權，請前往 [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell)。

    您可以引導使用者前往 Cloud Shell，協助他們快速開始使用專案；讓他們有機會逐步瞭解使用案例，並熟悉專案的功能。

    請繼續進行下一個步驟，開始設定教學課程。

  • 基本範例：

    • Hello World：您提供的第一個範例必須足夠簡單，讓使用者不用太多說明就能執行測試，其功用應該類似 Hello World。請以本範例為基礎，繼續透過本教學課程闡述各個概念。
    範例

    ## 情境式教學課程

    您現在看到的是情境內教學課程。

    內容會與 Cloud Shell 環境一併顯示，您可以在該環境中執行教學課程步驟。在同一處開啟教學課程和開發環境，可讓使用者透過簡單的單一畫面體驗，輕鬆開始使用專案。

    現在，請嘗試執行一個指令：

    ```bash

    echo "Hello Cloud Shell"

    ```

    **提示**：按一下程式碼方塊旁的「複製」按鈕，即可將指令貼到 Cloud Shell 終端機中執行。

    接著，您將編寫並啟動基本教學課程。

  • 教學課程內容

    • 謹慎使用格式工具：為文字加上格式 (如粗體、斜體等) 容易令人分心；除非必要或有明顯的用途 (如警告、學習重點等)，否則請避免使用。
    • 文法保持一致：描述使用者操作時應用祈使句，並且在句尾加上句號。
    • 參閱連結：在內容相關處加上補充連結 ([連結文字](連結網址))，以供使用者做進一步的研究。
    • 選擇螢幕截圖以外的醒目顯示方式：醒目顯示是一種動作，可醒目顯示 UI 元素在 Google Cloud 控制台中的位置，讓使用者不必搜尋圖片就能找出元素。
    • 替代檢視方式：如有可能，請提供以靜態內容方式呈現的教學課程內容連結；這將能讓使用者自由選擇要以何種方式使用所提供的資訊。
    • 提供實用提示：視情況加入提示 (以「**提示：**」標示)，為使用者提供更直覺的解決方案和最佳做法。
    範例

    ## 使用 Markdown 編寫

    如要撰寫教學課程，請使用 [Markdown](https://en.wikipedia.org/wiki/Markdown)，並遵守下列準則：

    ### 編輯標題

    修改本教學課程的標題 (「# Introduction to writing tutorials in Cloud Shell」)，將其變更為：

    ```

    # 教我編寫教學課程

    ```

    ### 新增步驟

    接下來，在標題之後新增一個步驟，如下所示：

    ```

    ## 步驟 1

    這是我們剛新增的步驟。

    ```

    教學課程的每個「步驟」都會顯示在一個頁面上。

    **提示**：使用者會使用「返回」和「繼續/前進」按鈕，在步驟之間移動。

  • 摘要

    • 恭喜：請務必加入一個獎盃圖示 (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) 來感謝使用者撥出時間完成教學課程。
    • 總結：概略說明您希望使用者從教學課程中得到的收穫。
    • 後續步驟：提供接下來的步驟，協助使用者順利完成教學旅程。這可以是建議閱讀的文章、輔助資源或甚至是其他教學課程。
    • 提醒使用者：建議使用者清除他們為了教學課程而建立的任何測試資源，以免被收取不必要的費用。
    範例

    ## 恭喜

    <walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>

    大功告成！

    使用者現在可以在 Cloud Shell 中啟動教學課程，輕鬆開始使用專案。

    如需 Cloud Shell 教學課程撰寫工具的完整清單，請參閱 [教學課程 Markdown 參考資料](https://cloud.google.com/shell/docs/tutorial-markdown-reference)。

    **別忘了做清除工作**：如果您先前建立了測試專案，請記得加以刪除，避免衍生不必要的費用。請使用「gcloud projects delete <PROJECT-ID>」。