mcpField
T
tutorial-docs

tutorial-docs

github.com/existential-birdsドキュメント85266 回インストール11 週間前に更新
リポジトリ

tutorial-docs について

tutorial-docsは、Diataxisに基づく実践型チュートリアルを書くスキルです。ガイドに沿って学ぶ初心者を対象とし、一本道の手順、各段階の可視化された成果、公開前の順次チェックを重視します。

主な機能

  1. 01Diataxisに沿った構成
  2. 02行動中心のガイド手順
  3. 03目に見える成果の確認
  4. 04初心者向けの執筆指針
  5. 05公開前の順次ゲート

活用シーン

  1. 01入門プロジェクトのチュートリアル作成
  2. 02期待結果を示す手順への修正
  3. 03公開前のチュートリアル確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/existential-birds/beagle --skill tutorial-docs

インストール後、Claude Code で/tutorial-docsを入力して読み込まれたか確認します。

同梱ファイルreferences/example-weather-api.md

詳細

チュートリアルドキュメントのスキル

このスキルでは、Diataxis フレームワークに沿って効果的なチュートリアルを書くためのパターンを紹介します。チュートリアルは学習を目的としたコンテンツで、教師の導きのもと、読者が実際に手を動かしながら学びます。

依存関係： 執筆の基本原則には、このスキルと docs-style を併用してください。ハウツー、リファレンス、解説ではなく、チュートリアルが適切かどうかを判断するには、docs-style/references/diataxis-compass.md を参照してください。

目的と対象読者

対象読者：

  • これまでの経験がない初心者
  • 特定のタスクを達成するのではなく、学びたいユーザー
  • プロダクトで初めて成功を体験したい人
  • 導きのある実践的な練習から学べる人

チュートリアルに含まれないもの：

  • 特定のタスクの達成を支援するハウツーガイド
  • 理解を促す解説
  • システムについて説明するリファレンスドキュメント

中核となる原則（Diataxis フレームワーク）

1. 読むのではなく、実際に手を動かして学ぶ

チュートリアルでは、説明ではなく行動を通じて教えます。読者は常に何かに取り組んでいる状態であるべきです。

避ける表現推奨する表現
「REST API は HTTP メソッドを使って……」「次のコマンドを実行して、初めての API 呼び出しを行います。」
「認証は……なので重要です」「認証するには API キーを追加します。」
「ダッシュボードには複数のセクションがあります……」「ダッシュボードで Create Project をクリックします。」
2. 各ステップで目に見える結果を示す

操作のたびに、読者に何が表示されるかを正確に伝えてください。これにより成功を確認でき、自信につながります。

Run the development server:

```bash
npm run dev

次のように表示されます。

> Local: http://localhost:3000
> Ready in 500ms

ブラウザーで http://localhost:3000 を開きます。「Hello, World!」と表示されたウェルカムページが表示されます。


### 3. One Clear Path, Minimize Choices

Tutorials should not offer alternatives. Pick one way and guide the reader through it completely.

| Avoid | Prefer |
|-------|--------|
| "You can use npm, yarn, or pnpm..." | "Install the dependencies:" |
| "There are several ways to configure..." | "Create a config file:" |
| "Optionally, you might want to..." | [Omit optional steps entirely] |

### 4. The Teacher Takes Responsibility

If the reader fails, the tutorial failed. Anticipate problems and prevent them. Never blame the reader.

```markdown
<Warning>
Make sure you're in the project directory before running this command.
If you see "command not found", return to Step 2 to verify the installation.
</Warning>
5. 自信につながるよう、繰り返しを取り入れる

少し異なる状況で似た操作を繰り返すと、学んだことが定着しやすくなります。効率化しようとしないでください。

6. 一人称複数で書く

Diataxis では、チュートリアルに「私たち」という語り口を用います。「このチュートリアルでは、私たちは……を作ります」「では、……を追加しましょう」「出力を確認しましょう」といった表現です。これは教師と学習者のつながりを示します。教師は学習者と一緒に取り組み、結果に責任を持ちます。「このコマンドを実行します」のような二人称の命令形は、読者が行う個々の操作に使い、学習の道筋は「私たち」を使って説明してください。

避ける表現推奨する表現
「あなたはダッシュボードを作ります。」「このチュートリアルでは、ダッシュボードを作っていきます。」
「次に、API を設定します。」「では、API を設定しましょう。」

チュートリアルのテンプレート

すべてのチュートリアルで次の構成を使用します。

---
title: "Build your first [thing]"
description: "Learn the basics of [product] by building a working [thing]"
---

# Build Your First [Thing]

In this tutorial, we'll build a [concrete deliverable]. By the end, you'll have a working [thing] that [does something visible].

<Note>
This tutorial takes approximately [X] minutes to complete.
</Note>

## What you'll build

[Screenshot or diagram of the end result]

A [brief description of the concrete deliverable] that:
- [Visible capability 1]
- [Visible capability 2]
- [Visible capability 3]

## Prerequisites

Before starting, make sure you have:

- [Minimal requirement 1 - link to install guide if needed]
- [Minimal requirement 2]

<Tip>
New to [prerequisite]? [Link to external resource] has a quick setup guide.
</Tip>

## Step 1: [Set up your project]

[First action - always start with something that produces visible output]

```bash
[command]

次のように表示されます。

[expected output]

[これが何を意味するかを簡潔に説明]

ステップ 2：[最初のものを作成する]

[次の操作を明確に指示]

[code to add or modify]

ファイルを保存します。［目に見える変化］が表示されます。

[よくある間違いを防ぐための任意のヒント]

ステップ 3：[作成を続ける]

[目に見える出力が得られるステップを続けます]

ステップ 4：[最後の要素を追加する]

最後のステップで、すべてをまとめます。

これで［最終的に目に見える結果］が表示されます。

[完成したプロジェクトのスクリーンショット]

学んだこと

このチュートリアルでは、次のことを学びました。

  • ［具体的なスキル 1：できるようになったこと］
  • ［具体的なスキル 2］
  • ［具体的なスキル 3］

次のステップ

［もの］が動作するようになったので、次のことに取り組めます。

  • ［チュートリアル 2 のタイトル］ - ［次の学習目標］を通じて学習を続けます
  • ［ハウツーガイド］ - ［もの］を使って［具体的なタスク］を行う方法を学びます
  • ［概念のページ］ - ［概念］について、さらに詳しく理解します

## Writing Principles

### Title Conventions

- **Start with action outcomes**: "Build your first...", "Create a...", "Deploy your..."
- Focus on what they'll make, not what they'll learn
- Be concrete: "Build a chat application" not "Learn about real-time messaging"

### Step Structure

1. **Lead with the action** - don't explain before doing
2. **Show exactly what to type or click** - no ambiguity
3. **Confirm success after every step** - "You should see..."
4. **Keep steps small** - one visible change per step

### Managing Prerequisites

Tutorials are for beginners, so minimize prerequisites:

```markdown
## Prerequisites

- A computer with macOS, Windows, or Linux
- A text editor (we recommend VS Code)
- 15 minutes of time

<Tip>
You don't need any programming experience. This tutorial explains everything as we go.
</Tip>
「次のように表示されます」パターン

これはチュートリアル執筆で最も重要なパターンです。常に活用してください。

Click **Save**. You should see a green checkmark appear next to the filename.

Run the test:

```bash
npm test

次のように表示されます。

PASS  src/app.test.js
  ✓ renders welcome message (23ms)

Tests: 1 passed, 1 total


### Handling Errors Gracefully

Anticipate failures and guide readers back on track:

```markdown
<Warning>
If you see "Module not found", make sure you saved the file from Step 2.
Return to Step 2 and verify the import statement matches exactly.
</Warning>

チュートリアルで使うコンポーネント

スクリーンショット用の Frame コンポーネント

成功時の状態を示します。

<Frame caption="Your completed dashboard should look like this">
  ![Dashboard screenshot](/images/tutorial-dashboard.png)
</Frame>
手順用の Steps コンポーネント

ステップ内で番号付きの手順を示す場合に使います。

<Steps>
  <Step title="Open the settings panel">
    Click the gear icon in the top right corner.
  </Step>
  <Step title="Find the API section">
    Scroll down to **Developer Settings**.
  </Step>
  <Step title="Generate a key">
    Click **Create New Key** and copy the value shown.
  </Step>
</Steps>
ガイダンス用のコールアウト
<Note>
Don't worry if the colors look different on your screen.
We'll customize the theme in the next step.
</Note>

<Warning>
Make sure to save the file before continuing.
The next step won't work without this change.
</Warning>

<Tip>
You can press Cmd+S (Mac) or Ctrl+S (Windows) to save quickly.
</Tip>
行を強調表示するコード

重要な箇所に注目を促します。

```javascript {3-4}
function App() {
  return (
    <h1>Hello, World!</h1>
    <p>Welcome to your first app.</p>
  );
}


## Example Tutorial

See [references/example-weather-api.md](references/example-weather-api.md) for a complete example tutorial demonstrating all principles above. The example builds a weather dashboard that fetches real API data.

## Checklist for Tutorials

Before publishing, verify:

- [ ] Title describes what they'll build, not what they'll learn
- [ ] Introduction shows the concrete end result
- [ ] Prerequisites are minimal (beginners don't have much)
- [ ] Every step produces visible output
- [ ] "You should see" appears after each significant action
- [ ] No choices offered - one clear path only
- [ ] No explanations of why things work (save for docs)
- [ ] Potential failures are anticipated with recovery guidance
- [ ] "What you've learned" summarizes concrete skills gained
- [ ] Next steps guide to continued learning
- [ ] Pre-publish gates (below) completed in order—not only self-reviewed

## Pre-publish gates

Run these **in order**. Start the next gate only after the previous **pass** is satisfied.

1. **Draft artifact** — The tutorial exists at a concrete path (file, branch, or CMS location). **Pass:** the artifact opens without guesswork.

2. **Observable outcomes** — **Pass:** every procedural step states what the reader should see next (command output, UI change, or named file)—not only what to do.

3. **Single path** — **Pass:** aside from prerequisite install links, the body does not branch into equivalent alternatives (“npm or yarn…”) unless you split into separate tutorials.

4. **Independent run** — Someone who did not write the draft follows the tutorial from a clean starting point. **Pass:** each step matches its promised outcome; any mismatch is fixed in the doc before publish (see “The Teacher Takes Responsibility” above).

## When to Use Tutorial vs Other Doc Types

| User's mindset | Doc type | Example |
|---------------|----------|---------|
| "I want to learn" | **Tutorial** | "Build your first chatbot" |
| "I want to do X" | How-To | "How to configure SSO" |
| "I want to understand" | Explanation | "How our caching works" |
| "I need to look up Y" | Reference | "API endpoint reference" |

For the full compass procedure and the other type distinctions, see [docs-style/references/diataxis-compass.md](../docs-style/references/diataxis-compass.md).

### Tutorial vs How-To: Key Differences

| Aspect | Tutorial | How-To |
|--------|----------|--------|
| **Purpose** | Learning through doing | Accomplishing a specific task |
| **Audience** | Complete beginners | Users with some experience |
| **Structure** | Linear journey with one path | Steps to achieve a goal |
| **Choices** | None - one prescribed way | May show alternatives |
| **Explanations** | Minimal - action over theory | Minimal - focus on steps |
| **Success** | Reader learns and gains confidence | Reader completes their task |
| **Length** | Longer, more hand-holding | Shorter, more direct |

## Related Skills

- **[docs-style](../docs-style/SKILL.md)**: Core writing conventions and components
- **[Diataxis compass](../docs-style/references/diataxis-compass.md)**: Type selection, the 2×2 map, and the quality model
- **[howto-docs](../howto-docs/SKILL.md)**: How-To guide patterns for task-oriented content
- **[reference-docs](../reference-docs/SKILL.md)**: Reference documentation patterns
- **[explanation-docs](../explanation-docs/SKILL.md)**: Conceptual documentation patterns

コメント

Markdown 対応