逐步操作說明編寫指南

為了讓使用者有效熟悉您的專案,這裡提供了一些方針,協助您運用教學課程圓滿呈現您的內容。

Cloud Shell 的特色

  • 獨特的版面配置:逐步操作說明會以側邊面板 (寬度為 310 像素) 的形式顯示於 Google Cloud Console 的右側。
  • 導覽:使用者可使用 [Continue] (繼續) 和 [Back] (上一步) 按鈕瀏覽整個教學課程。注意,要前往瀏覽過的步驟,應該使用 [Forward] (下一步) 按鈕 (而不是 [Continue] (繼續) 按鈕)。使用者也可以點選 [Cancel Tutorial] (取消教學課程) 來結束課程,之後再從中斷的地方繼續觀看。
  • 可攜式程式碼:您可以在教學課程中加入程式碼片段。這裡會以行內圖示 「複製」圖示 來代表程式碼,方便使用者直接將程式碼片段貼入 Cloud Shell。

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

含有教學課程窗格的主控台工作階段會在右側開啟。使用者可以利用行內圖示直接將程式碼複製到 Cloud Shell,並使用 [Back] (上一步) 和 [Continue] (繼續) 按鈕在頁面之間移動。

編寫風格

  • 語調輕鬆:教學課程應能提供充分的實用資訊,但語氣不需要太過正式。
  • 以第二人稱代名詞稱呼使用者:使用第二人稱代名詞 (請使用:您、您的;請勿使用:我們、我、我們的等)。
  • 說明因果關係:要求使用者執行一個步驟時,應說明動作背後的原因和預期結果。
  • 鎖定目標:在編寫教學課程之前,應先設定一個希望使用者達成的明確目標。編寫教學課程時應將這個目標謹記在心。
原始版本 修訂後的版本 改善方法
在下一頁中,您將學習如何建立新的教學課程。 繼續下個步驟,開始設定您的教學課程。 以使用者為主;使用主動語態

使用輕鬆的語言

執行下列指令:

``` 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 分鐘

    **必備條件**:GCP 帳戶

    按一下 **[Continue] (繼續)** 按鈕前往下一個步驟。

  • 背景頁面

    • 設定場景:在編寫教學課程時加入一些背景資訊,通常會很有幫助。這類的背景資訊包括提供簡要的產品概述,或是簡短介紹 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"

    ```

    **提示**:按一下程式碼方塊旁的 [Copy] (複製) 按鈕,可將指令貼到 Cloud Shell 終端機中執行。

    接下來,您將要編寫並啟動一個基本的教學課程。

  • 教學課程內容

    • 謹慎使用格式工具:為文字加上格式 (如粗體、斜體等) 容易令人分心;除非必要或有明顯的用途 (如警告、學習重點等),否則請避免使用。
    • 文法保持一致:描述使用者操作時應用祈使句,並且在句尾加上句號。
    • 參閱連結:在內容相關處加上補充連結 ([連結文字](連結網址)),以供使用者做進一步的研究。
    • 優先選用焦點功能,螢幕擷圖次之:焦點功能可突顯出 UI 元素在主控台中的位置,讓使用者不用搜尋圖片就能辨識出這些元素。
    • 替代檢視方式:如有可能,請提供以靜態內容方式呈現的教學課程內容連結;這將能讓使用者自由選擇要以何種方式使用所提供的資訊。
    • 最好能加入提示:如果可行,最好能加入一些提示 (寫法為「**提示:**」),為使用者提供更直觀的解決方案和最佳做法。
    範例

    ## 使用 Markdown 編寫

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

    ### 編輯標題

    將教學課程的標題 (「# 在 Cloud Shell 中編寫教學課程的簡介」) 修改為:

    ```

    # 教我編寫教學課程

    ```

    ### 新增步驟

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

    ```

    ## 步驟 1

    這是我剛加入的新步驟。

    ```

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

    **提示**:如要在步驟間移動,使用者可以使用 [Back] (上一步) 和 [Continue/Forward] (繼續/下一步) 按鈕。

  • 摘要

    • 恭喜:請務必加入一個獎盃圖示 (<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>」。

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Shell