チュートリアル記事の書き方フレームワーク

要点: 技術ドキュメントは Diátaxis の 4 象限 (Tutorial / How-to / Reference / Explanation) に分離するのが事実上の標準。Tutorial は「1 本道・具体先行・完走保証」の 3 点が肝。

Diátaxis フレームワーク#

Daniele Procida (Divio) 提唱。Django, Kubernetes, GitLab, NumPy, Cloudflare 等で採用。

混ぜないのが最重要。1 記事に複数種類を詰めると、どれとしても機能しない。

Tutorial の 6 ルール (Diátaxis)#

1. 完走できる保証: 全ステップで動く状態を保つ。壊れる例を出さない
2. 具体先行: 抽象概念を先に説明しない。動かして体験→後で名前付け
3. 選択肢を与えない: "A でも B でもいい" と書かない。1 本道
4. 成功を可視化: 各ステップの終わりに "こう見えるはず" を示す
5. 完全性より完走: 全部教えない。到達地点を先に決める
6. 説明の最小化: なぜ動くかは Explanation に逃がす。Tutorial は "やる" に集中

構造の定石#

多くの技術チュートリアル (Rust Book, Kubernetes, ROS2 公式) が共通で持つ要素:

• 前提知識 (Prerequisites) を冒頭に明記
• 学習目標 (What you'll learn) を 3~5 個の箇条書き
• 所要時間 の目安 (15 分、1 時間 等)
• チェックポイント: 動作確認コマンドと期待出力 (例: ros2 node list の結果)
• 次のステップ へのリンク

進行順の原則#

• Progressive disclosure (段階的開示): 最初は複雑さを隠して 1 概念だけ。次の記事で 1 つ足す
• Scaffolding (足場): 前の記事で扱った知識だけを前提にする。逆走禁止
• Zero to Hello, World first: 環境構築で挫折させない。最短で動く状態を作る
• 1 記事 1 概念: 20 分で読み切れる粒度が目安
• 既知→未知: 読者が既に持っている概念を経由して新概念に橋渡し

Anti-patterns#

• 抽象から始める: "ROS2 とはノードとトピックからなる分散システムで..." → 動かす前に脱落
• 選択肢の羅列: "cli/rqt/rviz どれでもいい" → どれを選ぶか迷って止まる
• 前提の未宣言: Linux CLI 前提を書かず C だけ知ってる読者に投げる
• 完全性の追求: 例外・エッジケースを Tutorial に混ぜる → How-to や Reference の仕事
• 暗黙のジャンプ: 前の記事で説明してない概念 (workspace 等) が突然出る
• 修辞的疑問: "なぜでしょうか?" 等の擬似的問いかけ → 進行を止める

Bloom's taxonomy との対応#

Tutorial は Bloom の下位 3 段 (Remember / Understand / Apply) を対象。上位 (Analyze / Evaluate / Create) は Explanation や Reference の役目。1 チュートリアルで全段カバーしようとしない。

主要参考文献#

• Diátaxis 公式: https://diataxis.fr/
• Divio Documentation System: https://documentation.divio.com/
• Google Developer Documentation Style Guide: https://developers.google.com/style
• Write the Docs: https://www.writethedocs.org/
• Rust Book (実装例): https://doc.rust-lang.org/book/

関連#

• Docs フレームワーク比較 — レンダリング側 (fumadocs 等)、この記事は執筆側
• Persistent AI memory systems