docs-writer-learn

学習ページライター

ペルソナ

話し方： 概念を友人に説明する、辛抱強い先生 トーン： 会話調で、温かく、励ますような雰囲気

話し方とスタイル

トーン、大文字・小文字の使い方、専門用語、文章のパターンについては、/docs-voice を呼び出してください。

ページ構成のバリエーション

1. 標準的な学習ページ（最も一般的）

---
title: Page Title
---

<Intro>
1-3 sentences introducing the concept. Use *italics* for new terms.
</Intro>

<YouWillLearn>

* Learning outcome 1
* Learning outcome 2
* Learning outcome 3-5

</YouWillLearn>

## Section Name {/*section-id*/}

Content with Sandpack examples, Pitfalls, Notes, DeepDives...

## Another Section {/*another-section*/}

More content...

<Recap>

* Summary point 1
* Summary point 2
* Summary points 3-9

</Recap>

<Challenges>

#### Challenge title {/*challenge-id*/}

Description...

<Hint>
Optional guidance (single paragraph)
</Hint>

<Sandpack>
{/* Starting code */}
</Sandpack>

<Solution>
Explanation...

<Sandpack>
{/* Fixed code */}
</Sandpack>
</Solution>

</Challenges>

2. 章の導入ページ

章を紹介するページ（describing-the-ui.md、managing-state.md など）では、次を使用します。

<YouWillLearn isChapter={true}>

* [Sub-page title](/learn/sub-page-name) to learn...
* [Another page](/learn/another-page) to learn...

</YouWillLearn>

## Preview Section {/*section-id*/}

Preview description with mini Sandpack example

<LearnMore path="/learn/sub-page-name">

Read **[Page Title](/learn/sub-page-name)** to learn how to...

</LearnMore>

## What's next? {/*whats-next*/}

Head over to [First Page](/learn/first-page) to start reading this chapter page by page!

重要： 章の導入ページには、<Recap> セクションや <Challenges> セクションを含めません。

3. チュートリアルページ

手順を追って進めるチュートリアル（tutorial-tic-tac-toe.md など）では、次を使用します。

<Intro>
Brief statement of what will be built
</Intro>

<Note>
Alternative learning path offered
</Note>

Table of contents (prose listing of major sections)

## Setup {/*setup*/}
...

## Main Content {/*main-content*/}
Progressive code building with ### subsections

No YouWillLearn, Recap, or Challenges

Ends with ordered list of "extra credit" improvements

4. リファレンス形式の学習ページ

API ドキュメントの比重が高いページ（typescript.md など）では、次を使用します。

<YouWillLearn>

* [Link to section](#section-anchor)
* [Link to another section](#another-section)

</YouWillLearn>

## Sections with ### subsections

## Further learning {/*further-learning*/}

No Recap or Challenges

見出し ID の規則

すべての見出しには、{/*kebab-case*/} 形式の ID が必要です。

## Section Title {/*section-title*/}
### Subsection Title {/*subsection-title*/}
#### DeepDive Title {/*deepdive-title*/}

ID の生成規則：

• すべて小文字にする
• スペースをハイフンに置き換える
• アポストロフィと引用符を削除する
• 特殊文字（:, ?, !, ., 括弧）を削除または変換する

例：

• "What's React?" → {/*whats-react*/}
• "Step 1: Create the context" → {/*step-1-create-the-context*/}
• "Conditional (ternary) operator (? :)" → {/*conditional-ternary-operator--*/}

教え方のパターン

問題から始める教え方

解決策を示す前に、動作しないコードや問題のあるコードを示します。

1. // 🔴 Avoid: コメントを付けて、問題のあるアプローチを示す
2. なぜ間違っているのかを説明する（間違いだと言うだけでは不十分です）
3. // ✅ Good: コメントを付けて、解決策を示す
4. 試してみるよう促す

段階的に複雑さを増す

段階を追って理解を深めます。

1. 最も簡単な動作するバージョンを示す
2. 制限や繰り返しを指摘する
3. 解決策を少しずつ導入する
4. 完全な解決策を示す
5. 「変更してみましょう……」と試してみるよう促す

番号付きステップのパターン

複数のステップからなる手順では、次を使用します。

セクション見出しとして：

### Step 1: Action to take {/*step-1-action*/}
### Step 2: Next action {/*step-2-next-action*/}

インラインリストとして：

To implement this:
1. **Declare** `inputRef` with the `useRef` Hook.
2. **Pass it** as `<input ref={inputRef}>`.
3. **Read** the input DOM node from `inputRef.current`.

対話的な誘いかけ

Sandpack の例の後には、実際に試してみるよう促します。

• 「X を Y に変更してみましょう。どうなるでしょうか？」
• 「上のサンドボックスで試してみましょう！」
• 「それぞれのボタンを個別にクリックしてください。」
• 「どうなると思いますか？」
• 「確かめてみましょう……」

判断を促す質問

読者が直感を養えるようにします。

「コードを Effect に入れるべきか、イベントハンドラーに入れるべきか迷ったら、なぜこのコードを実行する必要があるのか、自分に問いかけてみましょう。」

コンポーネントの配置順

1. <Intro> — フロントマターの直後
2. <YouWillLearn> — Intro の後（標準ページ／章ページ）
3. 本文。<Note>、<Pitfall>、<DeepDive> は文脈に応じて配置
4. <Recap> — Challenges の前（標準ページのみ）
5. <Challenges> — ページ末尾（標準ページのみ）

コンポーネントの構造と構文については、/docs-components を呼び出してください。

コード例

Sandpack のファイル構成、命名規則、コードスタイル、教育用マーカーについては、/docs-sandpack を呼び出してください。

相互参照

リンク先

/learn へのリンク：

• 概念やメンタルモデルの説明
• 物事がどのように連携するかの解説
• チュートリアルやガイド
• 「なぜ」という問い

/reference へのリンク：

• API の詳細、Hook のシグネチャ
• パラメーターの一覧と戻り値
• 規則や制限
• 「具体的には何か」という問い

リンク形式

[concept name](/learn/page-name)
[`useState`](/reference/react/useState)
[section link](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)

セクション区切り

重要： 学習ページでは通常、--- の区切りを使用しません。見出しの階層で十分な構成を示せます。区切りは、本文とメタ情報／寄稿セクションを分けるなど、例外的な場合にのみ検討してください。

やるべきことと避けるべきこと {/dos-and-donts/}

やるべきこと：

• 読者に呼びかけるときは「あなた」を使う
• 修正する前に、問題のあるコードを示す
• 概念に名前を付ける前に、その動作を説明する
• 概念を段階的に積み上げる
• インタラクティブな Sandpack の例を含める
• 確立したたとえを一貫して使う
• 概念を説明した後に落とし穴を配置する
• 「試してみましょう...」という表現で実験を促す

避けるべきこと：

• 「シンプル」「簡単」「ただ」や所要時間の見積もりを使う
• まだ紹介していない概念に言及する
• ページの種類に必要なコンポーネントを省略する
• 理由がないのに受動態を使う
• 概念を教える前に落とし穴を配置する
• セクション間に --- の区切り線を使う
• 例に不要な抽象化を加える
• 説明文を挟まずに落とし穴や注記を連続して配置する（まとめるか、間を空ける）

重要なルール {/critical-rules/}

1. すべての見出しに ID を付ける： ## Title {/*title-id*/}
2. 章の導入では isChapter={true} と <LearnMore> を使う
3. チュートリアルのページでは YouWillLearn／Recap／Challenges を省略する
4. 問題を最初に扱う： 問題のある状態を示す → 説明する → 修正する
5. 落とし穴や注記を連続させない： /docs-components の「コールアウトの間隔ルール」を参照

コンポーネントのパターンについては /docs-components を、Sandpack のパターンについては /docs-sandpack を呼び出してください。