- ほとんどのソフトウェアチュートリアルは重要な詳細を省いたり、読者の期待に合わない隠れた前提を含んでいたりするため、読者が手順を再現できないことが多い
- いくつかの簡単なルールに従えば、優れたチュートリアルを書くことは思っているより簡単
ルール
- 初心者向けに書く
- 明確な結果を約束するタイトルを書く
- 導入部で目標を説明する
- 最終結果を先に見せる
- コピペ可能なコードスニペットを書く
- コマンドでは長いフラグを使う
- ユーザー定義の値と再利用可能なロジックを分離する
- 読者の手間を減らす
- コードが常に動作する状態を保つように書く
- 1つのトピックだけを教える
- 装飾より明確さを優先する
- 依存関係を最小限にする
- ファイル名を明確に指定する
- 一貫性があり説明的な見出しを使う
- ソリューションが動作することを証明する
- 完全なサンプルをリンクする
初心者向けに書く
- チュートリアルでもっともよくある失敗は、初心者レベルの概念を専門家レベルの用語で説明してしまうこと。チュートリアルを探している人の大半は初心者
- プログラミング自体の初心者ではないかもしれないが、学ぼうとしているドメインでは初心者
- 初心者を対象に書き、専門的すぎる用語の使用は避ける
- 難しい用語を避け、読者が理解できる簡単な言葉で書く
- たとえば React チュートリアルでは、"JSX transpilation" の代わりに「React を使ったシンプルな Web ページの作成」のように説明する
明確な結果を約束するタイトルを書く
- タイトルは、読者がチュートリアルを通じて何を学べるのかを具体的に伝えるべき
- 不明確で曖昧なタイトルは避け、期待される結果をはっきり説明する
- 例: "Build a Real-Time Twitter Clone in 15 Minutes with Phoenix LiveView"
導入部で目標を説明する
- 読者がチュートリアルをクリックした時点で、あなたの話題にはすでに関心を持っている。しかし、読み進めてもらうにはさらに納得してもらう必要がある
- 読者が気にするのは次の2点
- この技術に関心を持つべきか?
- 関心があるなら、このチュートリアルは自分に合っているか?
- 導入部では、技術の重要性とチュートリアルの有用性を簡潔に説明する
- 読者の関心を引く有益な情報を示し、曖昧な記述は避ける
- 例: Docker チュートリアルでは、Docker が解決する問題と期待される結果を明確に説明する
最終結果を先に見せる
- できるだけ早い段階で、読者がチュートリアルを通じて作るもののデモやスクリーンショットを見せる
- チュートリアルの早い段階で最終結果を示し、目標を明確にする
- 例: 最終成果物のスクリーンショット、UI、動作例などを提示する
コピペ可能なコードスニペットを書く
- 読者がコードを簡単にコピーしてエディタやターミナルに貼り付け、そのまま実行できるように書く
- ターミナルのプロンプト文字
$ のような不要な要素は取り除く
- 非対話型フラグを使ってコマンドを簡略化し、失敗時に停止するよう
&& を使う
コマンドでは長いフラグを使う
- コマンドでは短いフラグよりも説明が明確な長いフラグを使い、初心者にも理解しやすくする
ユーザー定義の値と再利用可能なロジックを分離する
- コード内でユーザーが変更すべき値と、変更すべきでないコードを明確に分ける
- 環境変数を使ってユーザー定義の値を定義し、コードの可読性を高める
読者の手間を減らす
- 読者にチュートリアルを気に入ってもらえるよう、彼らの時間を尊重する
- 面倒な作業はコマンドスニペットで置き換える
- 例: 手作業でファイルを編集する代わりにコマンドで解決する
コードが常に動作する状態を保つように書く
- サンプルコードは常に実行可能であるべきで、中間段階でも動作する状態を保つ
- 間違ったコードや動かない例は読者を混乱させる
1つのトピックだけを教える
- チュートリアルは単一のトピックを中心に構成し、無関係な技術を混ぜない
- たとえば、検索機能を説明するチュートリアルに不要な AI 技術を追加しない
装飾より明確さを優先する
- 読者は、おもちゃのようなアプリケーションが美しく見えるかどうかを気にしない
- 不要な CSS やデザイン要素は最小限にし、核心となる概念に集中する
- 複雑な例ではなく、シンプルなコードで概念を明確に伝える
依存関係を最小限にする
- 読者がインストールすべき依存関係を最小限にして、チュートリアルの敷居を下げる
- 必須の依存関係を明確に示し、特定バージョンを明記する
ファイル名を明確に指定する
- 読者に、修正すべきファイルパスと内容を正確に案内する
- たとえば「config ファイルに設定を追加」と書く代わりに、完全なファイルパスと、どの行を編集すべきかまで具体的なコードで示す
一貫性があり説明的な見出しを使う
- 読者がチュートリアルをざっと見やすいよう、構造化された見出しを使う
- 見出しを使ってチュートリアルを構造化し、論理的な流れが反映されるようにする
- 見出しの形式、視点、時制を一貫して保つ
ソリューションが動作することを証明する
- チュートリアルがツールのインストールや複数コンポーネントの統合を教えるなら、その結果の使い方を見せる
- インストール・統合したツールの動作結果を読者に視覚的に示す
- たとえば nginx の成功ページを見せ、URL で確認する方法を案内する
完全なサンプルをリンクする
- チュートリアルのすべてのコードを含むリポジトリをリンクし、全体の流れを確認できるようにする
- 各ステップのコードを別々の git ブランチに分け、読者が各段階を追えるようにする
11件のコメント
参考用
これはワード！
いい文章ですね。
最近Dagsterのチュートリアルを試してみて、よくできているなと思いました。
https://courses.dagster.io/
Dagsterのチュートリアルを一通り見ましたが、すごく良いですね。
Djangoのチュートリアルは内容は充実しているのですが、長すぎて私はあまり好みではありません。もう少し分割してくれるといいですね。
よくできたチュートリアルの事例として、Django もあります https://docs.djangoproject.com/en/5.1/intro/tutorial01/
簡潔な言葉を使い、最終結果を最初に示す。
フレームワークの退屈な基礎的な使い方を見せるのではなく、
このフレームワークがどれほど素晴らしいかを見せようとするチュートリアル文書は、しばしばあります。
Get started に入ってみたら、基礎的な使い方のチュートリアルだと表示されているものが10ページもある文書だと、本当に嫌です。
みなさんすごすぎますね……
https://tanstack.com/table/latest/docs/introduction
https://github.com/tmux/tmux/wiki/Getting-Started