チュートリアルページの種類

チュートリアルは、複雑なワークフローやシナリオのエンドツーエンドのウォークスルーを含むページです。一般的に、以下のような場合にチュートリアルの使用を検討することができます：

  • ワークフローがいくつかの連続したステップを必要とし、各ステップがサブステップで構成されている場合。
  • ステップはGitLabの様々な機能やサードパーティのツールをカバーします。

チュートリアルガイダンス

  • チュートリアルはタスクではありません。タスクは1つの手順を指示するものです。チュートリアルは特定の目標を達成するために複数のタスクを組み合わせます。
  • チュートリアルは作業例を提供します。理想的には、読者はチュートリアルが説明する例を作ることができます。正確に再現できなくても、似たようなことは再現できるはずです。
  • To-Doは新しい機能を紹介するものではありません。
  • チュートリアルは、「真実の単一の情報源（Single Source of Truth）」の原則に従う必要はありません。他の場所で利用可能なコンテンツを複製することは理想的ではありませんが、読者が必要なものを見つけるためにページを離れることを強いるのは最悪です。

チュートリアルのファイル名と場所

チュートリアルのMarkdownファイルには、以下のいずれかを使用できます：

  • 製品ドキュメントのあるディレクトリにファイルを保存します。
  • doc/tutorials の下にサブフォルダを作成し、ファイル名をindex.md とします。

左側のナビで、関連する機能のドキュメントの近くにチュートリアルを追加します。

チュートリアルページの1つにチュートリアルへのリンクを追加します。

チュートリアルの形式

チュートリアルの形式は以下の通りです：

# Title (starts with "Tutorial:" followed by an active verb, like "Tutorial: Create a website")

A paragraph that explains what the tutorial does, and the expected outcome.

To create a website:

1. [Do the first task](#do-the-first-task)
1. [Do the second task](#do-the-second-task)

## Prerequisites

This topic is optional.

- Thing 1
- Thing 2
- Thing 3

## Do the first task

To do step 1:

1. First step.
1. Another step.
1. Another step.

## Do the second task

Before you begin, make sure you have [done the first task](#do-the-first-task).

To do step 2:

1. First step.
1. Another step.
1. Another step.

このフォーマットに従ったチュートリアルの例はTutorialです：最初の Git コミットを作成しましょう。

チュートリアルのページタイトル

ページタイトルはTutorial: の後にTutorial: Create a website のようにアクティブな動詞を続けてください。

左側のナビでは、ページタイトルをフルに使ってください。省略しないでください。パイプラインが通るように、テキストを引用符で囲んでください。例えば、"Tutorial: Make your first Git commit" 。

Learn GitLab with tutorialsページでは、タイトルにTutorial を使わないようにしましょう。

スクリーンショット

チュートリアルでは、プロセスの重要なステップを説明するためにスクリーンショットを含めることができます。Core 製品のドキュメントでは、スクリーンショットの使用は控えめにしてください。しかし、チュートリアルでは、スクリーンショットを使用することで、ユーザーが複雑なプロセスのどの段階にいるのかを理解することができます。

チュートリアルのスクリーンショットの数は、ストーリーの流れを妨げないようにバランスを取るようにしてください。例えば、チュートリアルの途中に大きなスクリーンショットを1枚掲載するのはやめましょう。その代わりに、複数の小さなスクリーンショットを全体に配置します。

チュートリアルの音声

他のトピックタイプよりも親しみやすい口調で話してください。例えば

  • タスクの後に励ましや祝福のフレーズを追加します。
  • 特にステップを紹介するときには、時折未来形を使いましょう。例えば、Next, you will associate your issues with your epics 。
  • もっと会話的に。例えば、This task might take a while to complete 。

メタデータ

チュートリアルのページでは、最も適切なstage: とgroup: メタデータをファイルの先頭に追加してください。コンテンツの大半が1つのグループにまとまっていない場合は、ステージにnone を、グループにTutorials を指定してください：

stage: none
group: Tutorials