チュートリアル作成ガイド

ユーザーがプロジェクトに効率よく慣れ親しむために、チュートリアル形式を使用してコンテンツをベストなやり方で提供するために役立つ、いくつかのガイドラインを示します。

Cloud Shell の特長

  • ユニークなレイアウト: チュートリアルは、Google Cloud Console の右側にあるサイドパネル(幅 310 ピクセル)に表示されます。
  • ナビゲーション: ユーザーは、[続行] および [戻る] ボタンを使用してチュートリアルを前後に移動できます。戻ったステップを進める場合、使用するボタンは [進む] です([続行] ではありません)。また、ユーザーは [チュートリアルをキャンセル] を使ってチュートリアルを終了することもでき、後で中断した場所から再開することもできます。
  • 使用するコード: チュートリアルにコード スニペットを含めることができます。これらはこのインライン アイコン コピーアイコン でフォーマットされたコードになり、ユーザーはこれらのスニペットを 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!

このガイドでは、ユーザー独自のインタラクティブなチュートリアルを構築する方法を紹介します。また、完成したチュートリアルを起動するためにユーザーが使用できるボタンの生成方法についても説明します。

チュートリアルで扱うレッスンのロードマップを明確にする

コンテンツを作成する際には、この点に注意してください。

おすすめの方法

  • 内容を短くする: チュートリアル ペインに固有のスペース制約があるため、ユーザーに一度に提供できる情報量は限られています。目を通すことが困難で垂直スクロールが必要な大量のテキストを避けてください。たやすく把握できる量の情報を提供することが望まれます。

    • 1 ページあたりのステップは 5 つまで、コード スニペットは 3 つまでにすることを心掛けます。

    • 段落は 5 行以下とするのが理想的で、単一のコンセプトを扱うようにします。

    • ページを長くする必要がある場合は、ペインの長さの最大 2 倍までにすることを心掛けます。

    • コードとターミナル ブロックは、一度に読み取れる小さいサイズにします。

      • なるべく 10 行以下にします。
      • 水平スクロールを減らすために、1 行につき 80 文字以下になるようにします。
      • ユーザーが一括コピー実行を行わないように、複数コマンドのコードブロックは避けます。
  • 前置きのページ: チュートリアルは前置きから始めます。

    • 期待を抱かせる: ユーザーがこのチュートリアルを完了することから得られるメリットを簡単に説明します。
    • 推定作業時間: ユーザーがチュートリアルに費やす時間をおおまかに見積もります。15 分以内に終了できるチュートリアルの作成を心掛けます。チュートリアルが長い場合(つまり、文字が詰まったページが 15 ページを超える場合)、一連の小さなチュートリアルに分割することを検討します。
    • 事前の準備: チュートリアルを中断なく進めるために設定が必要となる前提条件リソースやアクセス権を明記します。

    ## さあ始めましょう。

    インタラクティブなチュートリアルを組み込むことで、ユーザーは素早くプロジェクトを利用できます。

    このガイドでは、ユーザー独自のインタラクティブなチュートリアル(このガイドのようなもの)を作成する方法を説明します。また、完成したチュートリアルを起動するためにユーザーが使用できるボタンの生成方法についても説明します。

    **所要時間**: 約 10 分

    **前提条件**: GCP アカウント

    **[続行]** ボタンをクリックして次のステップに進みます。

  • バックグラウンド ページ

    • シーンを設定する: チュートリアルを書くときは、背景情報を与えると役立つことがよくあります。これは、プロダクトの概要を簡単に説明したり、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 環境とともに表示されます。チュートリアルと開発環境を同じ場所に開くことで、ユーザーは単純な 1 画面操作でプロジェクトを簡単に使い始めることができます。

    今すぐコマンドを実行してみてください。

    ```bash

    echo "Hello Cloud Shell"

    ```

    **ヒント**: コードボックスの横にあるコピーボタンをクリックして、コマンドを Cloud Shell ターミナルに貼り付けて実行します。

    次に、基本的なチュートリアルを作成して起動します。

  • チュートリアルの内容

    • フォーマットの使用の注意: テキストの書式設定(太字、イタリック体など)は読者の気を散らします。有効で必要な場合(警告、重要な学習事項を明記する場合など)にのみ使用してください。
    • 一貫性のある文法: ユーザーの操作を記述するときには命令形を使用し、句点で文を終えてください。
    • リンクの参照: 文脈で必要な場合は補足的なリンク([リンクテキスト](リンク URL))を付け、ユーザーが独自の調査を行えるようにします。
    • スクリーンショット上のスポットライトを選択する: スポットライトは、UI 要素がコンソールのどこにあるかを強調表示するアクションであり、ユーザーが画像を検索せずに要素を識別できるように位置を示します。
    • 代替ビュー: 可能であれば、チュートリアル コンテンツへのリンクを静的コンテンツとして提供します。これにより、ユーザーは、提供された情報をどのように使用するかを自由に選択できます。
    • ヒントの推奨: 適切な場合は、より直感的なソリューションとベスト プラクティスをユーザーに提供するためのヒント(「**ヒント:**」で指定する)を追加します。

    ## Markdown 形式での記述

    チュートリアルを書くには、[Markdown](https://en.wikipedia.org/wiki/Markdown)を使用し、次のガイドラインに従います。

    ### タイトルを編集する

    このチュートリアルのタイトル(「# Cloud Shell でのチュートリアルの作成の概要」)を、次のように変更します。

    ```

    # チュートリアルの書き方を学習する

    ```

    ### 新しいステップを追加する

    次に、タイトルの直後にこのようなステップを追加します。

    ```

    ## ステップ 1

    これは今追加した新しいステップです。

    ```

    チュートリアルの各ステップは 1 ページに表示されます。

    **ヒント**: ステップを前後に移動するには、[戻る] と [続行] / [進む] の各ボタンを使用します。

  • まとめ

    • 感謝の意を示す: チュートリアルを完了するために時間を割いたユーザーに感謝の意を示すトロフィー アイコン(<walkthrough-conclusion-trophy></ walkthrough-conclusion-trophy>)を必ず追加してください。
    • 締めくくり: ユーザーにチュートリアルから学習して欲しい重要な知識を要約します。
    • 次のステップ: 次のステップを提供することで、ユーザーの学習過程を支援します。こうしたステップは、おすすめのドキュメントや補足資料のほかに、別のチュートリアルである可能性があります。
    • ユーザーへの注意: チュートリアルの目的のために作成したすべてのテストリソースをクリーンアップして、不要な請求料金を回避するようアドバイスします。

    ## これで終わりです。

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

    すべて完了しました。

    Cloud Shell でユーザーがチュートリアルを起動し、プロジェクトを簡単に使い始めてもらうことができるようになりました。

    Cloud Shell チュートリアルの作成ツールのリストについては、[チュートリアル マークダウン リファレンス](https://cloud.google.com/shell/docs/tutorial-markdown-reference)をご覧ください。

    **作業後は忘れずにクリーンアップする**: テスト プロジェクトを作成した場合は、不要な料金の発生を避けるためにプロジェクトを削除してください。「gcloud projects delete <PROJECT-ID>」を使用します。

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...