チュートリアルのスタイルガイド

次のガイドラインは、ユーザーが効率的にプロジェクトを理解できるように、チュートリアル形式のコンテンツを表示できるようにしています。

Cloud Shell の特長

ユニークなレイアウト: チュートリアルは、Google Cloud Console の右側にあるサイドパネルに表示されます。
ナビゲーション: 各ステップの [次へ] ボタンと [前へ] ボタンを使用して、チュートリアルを進めることができます。また、チュートリアルを閉じ、中断したところから再開することもできます。
使用するコード: コードスニペットを Cloud Shell に直接コピーできます。

チュートリアルを開始した Google Cloud コンソールセッション

チュートリアルペインが表示された Cloud Shell エディタセッション。ボタンをクリックすることで Google 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 分前提条件: Cloud 請求先アカウント [続行] ボタンをクリックして次のステップに進みます。

バックグラウンドページ

シーンを設定する: チュートリアルを書くときは、背景情報を与えると役立つことがよくあります。これは、プロダクトの概要を簡単に説明したり、UI の顕著な機能を要約したりすることを意味します。

例	## Cloud Shell とは始める前に、Cloud Shell で行えることについて簡単に説明します。 Cloud Shell は、Google Cloud プロダクトのデベロッパーツールがプリロードされているパーソナルホスト型仮想マシンです。このインタラクティブなシェル環境には、コードエディタ、永続ディスクストレージ、およびウェブプレビュー機能が組み込まれています。コマンドラインアクセスだけを使用するには、[console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell）にアクセスしてください。ユーザーを Cloud Shell に誘導して、ユーザーがプロジェクトをすぐに使い始めるよう支援できます。そして、ユーザーがユースケースを順を追って実行し、プロジェクトの機能に慣れるための機会を与えます。次のステップに進んでチュートリアルの設定を開始します。

例

## 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 ターミナルに貼り付けて実行します。次に、基本的なチュートリアルを作成して起動します。

例

## コンテキスト内チュートリアル

現在表示されているのは、コンテキスト内チュートリアルです。

コンテンツは、チュートリアルの手順を実行できる Cloud Shell 環境とともに表示されます。チュートリアルと開発環境を同じ場所に開くことで、ユーザーは単純な 1 画面操作でプロジェクトを簡単に使い始めることができます。

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

```bash

echo "Hello Cloud Shell"

```

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

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

チュートリアルの内容

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

例	## Markdown 形式での記述チュートリアルを書くには、[Markdown]（https://en.wikipedia.org/wiki/Markdown）を使用し、次のガイドラインに従います。 ### タイトルを編集するこのチュートリアルのタイトル（「# Cloud Shell でのチュートリアルの作成の概要」）を、次のように変更します。 ``` # チュートリアルの書き方を学習する ``` ### 新しいステップを追加する次に、タイトルの直後にこのようなステップを追加します。 ``` ## ステップ 1 これは今追加した新しいステップです。 ``` チュートリアルの各ステップは 1 ページに表示されます。ヒント: ステップを前後に移動するには、[戻る] と [続行] / [進む] の各ボタンを使用します。

例

## 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>」を使用します。

例

## これで終わりです。

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

すべて完了しました。

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

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

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