チュートリアル

チュートリアルは、初心者を何もない状態から動くプロジェクトまで導きます。目に見える成果を一つずつ積み上げ、責任はすべて著者が負います。トーンは案内的で、率直、教育的、かつ権威あるものです。

製品の複数の部品を、実際のプロジェクトとして組み立てる必要があるときにチュートリアルを書きます。機能が連携して初めて価値が見える種類のものです。作成と正確な維持のコストが最も高いタイプなので、意図を持って選びます。次のものではありません。

• クイックスタート。 クイックスタートは数分で製品が動くことを示します。チュートリアルは、約 1 時間かけて意味のあるプロジェクトを通じて習熟を育てます。
• how-to。 how-to は、自分で進める習熟した読者向けです。チュートリアルの読者は何も知りません。何かが壊れたら、それはチュートリアルの責任です。
• 概念の講座。 チュートリアルは説明ではなく実践で教えます。概念は展開せず、リンクします。

全体の比較は コンテンツタイプ を参照してください。実際の例は Workers のチュートリアル を参照してください。

• タイトル: 結果で名付けた、二人称の命令形の短い動詞句です。例: "Build an order-notification service"。「Learn ...」や「Tutorial 1」は使いません。
• 説明: 読者が何を作り、そのあと何ができるようになるかを述べ、正直な所要時間を示します。

Nimbus の tutorial レシピを使って、このページを生成します。コーディングエージェントがページのひな形と自己レビュー用チェックリストを取得し、製品に合わせて調整します。

npx @cloudflare/nimbus-docs add content-tutorial

yarn @cloudflare/nimbus-docs add content-tutorial

pnpm @cloudflare/nimbus-docs add content-tutorial

レシピが出力する frontmatter を Cloudflare のスキーマに合わせて調整します。レシピが出力する type などの汎用フィールドではなく、pcx_content_type と products を設定します。

• Steps または番号付きの ## セクションが骨格です。各パートの末尾に、成功を証明する "You should see" の出力を原文どおり載せます。省略してはいけません。
• 読者が実際につまずく箇所の エラー回復の本文 は、例外のコールアウトではなくハッピーパスの一部です。チュートリアルでは想定済みのエラーは例外ではありません。
• GitHubCode と PackageManagers でサンプルコードとインストールコマンドを固定し、同期を保ちます。ListTutorials は一覧にチュートリアルを表示します。
• 向かないもの: あらゆる種類の Tabs と選択肢（著者はすでに 1 本の道を選んでおり、スタックごとの違いはページごとにします）、長い概念の脱線（代わりにリンクします）、ステップを隠すもの。

pcx_content_type: tutorial
difficulty: Beginner
products:
  - product-a
  - product-b

difficulty は Beginner、Intermediate、Advanced のいずれかにします。チュートリアルを最初から最後まで実行した日付を reviewed に記録します。詳細は pcx_content_type を参照してください。

チュートリアルは、正確に保つコストが最も高いタイプです。毎回、どの読者にも、初期状態のマシンで動かなければなりません。壊れたチュートリアルは、初心者に製品自体が壊れていると思わせます。少なく、新しいものが勝ちます。検証済みのチュートリアル 1 本は、古いチュートリアル 5 本に勝ります。チュートリアルが依存するすべてのバージョンを固定し、リリースごとにクリーンな環境で最初から最後まで再実行し、その日付を reviewed に記録します。

• ListTutorials

• 自己完結したパート。 各パートに、十分な文脈の見出し、コマンド全文、結果の原文を載せます。チュートリアルの途中から入った読者やエージェントが、いまどこにいるか分かるようにします。「上記で設定したとおり」のような位置参照は使いません。
• リテラルな出力。 期待する出力は、完全で現実的な値を入れたフェンス付きコードブロックにします。エージェントと読者が照合するのは、この "You should see" のテキストです。
• バージョンの固定。 前提条件ですべてのバージョンを明示して固定します。チュートリアルが最新リリースから静かにずれないようにします。