初心者に分かりやすい技術文書の作り方

初心者にわかる技術文書の書き方 README・チュートリアルを査読済み論文から考える徹底解説（増補版） うさうさ研修工房

目次 • 1. なぜ初心者はマニュアルを読まないのか • 2. ミニマリスト・インストラクションの原則 • 3. エラーからすぐ回復できる設計 • 4. 認知負荷：一度に教えすぎない • 5. 例題を先に見せる（worked example） • 6. 自己説明効果：仕組みを自分の言葉で言わせる • 7. 経験者には手厚い説明が逆効果になり得る • 8. 見出し・シグナリングが読解を助ける • 9. プログラミング初心者がつまずく6つの壁 • 10. 動画チュートリアルと文章チュートリアルの比較 • 11. 開発者はドキュメントに何を求めるか • 12. APIドキュメントが失敗する理由 • 13. READMEの内容分類（実証研究） • 14. 少人数のユーザーテストで大半の問題が見つかる • 15. 初心者徹底解説フォーマット • 16. 1ステップの書き方（実例） • 17. よくある失敗と対策

1. なぜ初心者はマニュアルを読まないのか • ユーザーはマニュアルを読まず、いきなり操作を試す傾向が観察されている • 「読むより試す」行動は、初心者にも経験者にも共通して見られると報告されている • 目的（動かしたい）が先にあり、説明は後回しにされる心理があると考えられている • 徹底解説を書く際は「読ませる」前提でなく「触りながら読む」前提で設計する必要がある 根拠：Novick, D. G., & Ward, K. (2006). Why don't people read the manual? Proc. SIGDOC 2006。

2. ミニマリスト・インストラクションの原則 • 「最小限マニュアル」は、説明を削り、実際の作業から始めさせる設計として提唱された • 実験では、通常のマニュアルより最小限マニュアルを使った利用者の方が作業を早く完了できたと報告 されている • 原則は「すぐ行動させる」「現実的な作業をさせる」「エラー回復を助ける」「読む量を減らす」の4つ に整理される • 詳しく書くことと最小限にすることの両立が、徹底解説の課題になる 根拠：Carroll, Smith-Kerker, Ford & Mazur-Rimetz (1987). Human-Computer Interaction, 3(2), 123–153；van der Meij & Carroll (1998). Technical Communication.

3. エラーからすぐ回復できる設計 • 初心者はマニュアル通りに進めても、必ずどこかでエラーに遭遇すると報告されている • ミニマリスト設計では、エラーを「起きるもの」として前提し、回復方法をあらかじめ用意しておく • エラーメッセージをそのまま載せ、原因と対処をセットで示すことが推奨される • 「エラーが起きない前提」で書かれた手順書は、実際の利用場面で機能しにくいとされる 根拠：Carroll et al. (1987)；van der Meij & Carroll (1998)。

4. 認知負荷：一度に教えすぎない • 人が一度に処理できる新しい情報の量には限りがあるとされる（認知負荷理論） • 1つのステップで複数の新しい概念を同時に扱うと、理解が追いつかなくなりやすい • 「1ステップ1動作」の設計は、この負荷を抑える具体的な方法として位置づけられる • 図と文字を同時に処理させる場合も、対応関係をわかりやすくすることが負荷軽減につながるとされる 根拠：Sweller, J. (1988). Cognitive Science, 12(2), 257–285。

5. 例題を先に見せる（worked example） • 問題の解き方をゼロから考えさせるより、完成した例を先に見せた方が初心者の学習が進みやすいと報 告されている • 複数の研究をまとめた分析でも、例題を使った学習の効果が支持されている • 「まず動くコード・完成形を見せてから、仕組みを説明する」構成に対応する • 徹底解説の冒頭に「完成イメージ」を置く設計は、この考え方に沿っている 根拠：Sweller & Cooper (1985). Cognition and Instruction, 2(1)；Atkinson et al. (2000). Rev Educ Res, 70(2), 181–214。

6. 自己説明効果：仕組みを自分の言葉で言わせる • 例題を読みながら「なぜこのステップが必要か」を自分の言葉で説明させると、学習成績が高くなると 報告されている • この現象は「自己説明効果」と呼ばれ、優れた学習者ほど自発的に自己説明をしている傾向が観察され た • 徹底解説に「なぜこの手順が必要か」を問いかける一文や、読者に説明させる練習課題を入れることが 応用にあたる • ただし、自己説明を促すだけで自動的に効果が出るわけではなく、質の高い自己説明を引き出す工夫が 必要とされる 根拠：Chi, M. T. H., Bassok, M., Lewis, M. W., Reimann, P., & Glaser, R. (1989). Self-explanations. Cognitive Science, 13(2), 145–182。

7. 経験者には手厚い説明が逆効果になり得る • 初心者向けの詳しい説明は、経験者にとってはかえって負担になり、成績が下がる場合があると報告さ れている（専門性逆転効果） • 経験者がすでに持っている知識と詳しい説明が重複し、余計な処理を強いるためと考えられている • 徹底解説では、初心者ルートと経験者向けの近道（折りたたみ等）を分ける設計が有効とされる • 「全員に同じ詳しさ」で書くことが、必ずしも親切とは限らない 根拠：Kalyuga, Ayres, Chandler & Sweller (2003). Educational Psychologist, 38(1), 23–31。

8. 見出し・シグナリングが読解を助ける • 文章に見出しや強調（シグナリング）を加えると、読者が重要な情報を見つけやすくなると報告されて いる • 特に、文章の構造をあらかじめ示す（目次・見出し階層）ことが、内容の記憶や検索のしやすさに関連 するとされる • 技術文書でも、見出しの階層を飛ばさず、内容のまとまりごとに区切ることが理解を助けると考えられ る • 過剰な強調（太字・色の乱用）は、逆に重要な情報を埋もれさせる可能性がある 根拠：Lorch, R. F. (1989). Text-signaling devices and their effects on reading and memory processes. Educational Psychology Review, 1(3), 209–234。

9. プログラミング初心者がつまずく6つの壁 壁 内容 設計の壁 何をすればよいか目標自体がわからない 選択の壁 使える機能・コマンドの中から何を選べばよいかわからない 調整の壁 複数の要素を組み合わせる方法がわからない 利用の壁 選んだ機能の具体的な使い方がわからない 理解の壁 なぜそう動くのか、仕組みが理解できない 情報の壁 必要な情報がどこにあるか見つけられない 根拠：Ko, A. J., Myers, B. A., & Aung, H. H. (2004). Six learning barriers in end-user programming systems. Proc. IEEE VL/HCC 2004, 199–206。

10. 動画チュートリアルと文章チュートリアルの比較 • ソフトウェアの学習において、動画チュートリアルと文章（紙・PDF）チュートリアルを比較した研究 がある • 学習成果そのものには大きな差が見られなかった一方、動画の方が学習者の満足度が高い傾向が報告さ れている • 文章は自分のペースで読み返しやすく、動画は操作の流れを直感的に把握しやすいという特性の違いも 指摘されている • 徹底解説では、文章の手順に加え、要所だけ動画やGIFを補助的に使う組み合わせが考えられる 根拠：van der Meij, H., & van der Meij, J. (2014). A comparison of paper-based and video tutorials for software learning. Computers & Education, 78, 150–159。

11. 開発者はドキュメントに何を求めるか • ソフトウェア開発者を対象にした調査では、最新性（内容が古くないこと）と正確さが、ドキュメント への不満の主な理由として挙げられている • コード例が実際に動くこと（コピーしてすぐ試せること）への要求も高いと報告されている • ドキュメントの整備は、多くの開発チームで優先順位が低くなりがちであることも指摘されている • 徹底解説を書く際も、実際に動作確認したコード例を載せることが信頼につながる 根拠：Aghajani et al. (2020). Software documentation: The practitioners' perspective. Proc. ICSE 2020；Meng, Steinhardt & Schubert (2018). J. Technical Writing and Communication.

12. APIドキュメントが失敗する理由 • APIドキュメントの問題を分類した研究では、「情報が古い」「説明が不十分」「例が足りない」が主な 失敗パターンとして挙げられている • 特に、実際のコード例の不足は、利用者の理解を妨げる大きな要因とされる • この知見は、README・チュートリアルにも応用できる：最短で動く例を必ず用意することが重要 • 説明文だけのドキュメントより、動くコード例つきのドキュメントの方が実用性が高いと考えられる 根拠：Uddin, G., & Robillard, M. P. (2015). How API documentation fails. IEEE Software, 32(4), 68 –75。

13. READMEの内容分類（実証研究） • 多数のGitHubリポジトリのREADMEを分析した研究では、内容が「これは何か」「なぜ使うか」「使い 方」「貢献方法」などのカテゴリに分類できると報告されている • この分類は、README作成時の章立ての参考になる • 内容の充実度とリポジトリの利用されやすさ（スター数等）との関連も分析されているが、因果関係は 明らかでない • 徹底解説の型は、この分類に「用語辞典」「仕組み解説」「よくあるエラー」を足した拡張版として位 置づけられる 根拠：Prana, Treude, Thung, Atapattu & Lo (2019). Categorizing the content of GitHub README files. Empirical Software Engineering, 24(3), 1296–1327。

14. 少人数のユーザーテストで大半の問題が見つかる • ユーザビリティ調査を数理モデルで分析した研究では、少人数（目安として5人程度）のテストで、使い やすさの問題の大部分が発見できると報告されている • 人数を増やすほど新たに見つかる問題は減っていく（収穫逓減）ことが示されている • 徹底解説も、公開前に3〜5人に実際に読んで操作してもらうだけで、大きな改善点が見つかる可能性が ある • 対象読者に近い人（初心者）にテストしてもらうことが重要である 根拠：Nielsen, J., & Landauer, T. K. (1993). A mathematical model of the finding of usability problems. Proc. CHI 1993, 206–213。目安人数には異論もある。

15. 初心者徹底解説フォーマット 要素 目的・根拠 完成イメージ 例題を先に見せる原則（Atkinson et al., 2000） 前提・用語辞典 情報の壁への対応（Ko et al., 2004） 全体像の図 見出し・シグナリングによる構造の提示（Lorch, 1989） 1ステップ1動作 認知負荷を抑える（Sweller, 1988） 「なぜ」を問う一文 自己説明効果（Chi et al., 1989） 動くコード例 開発者が求める要素（Meng et al., 2018；Uddin & Robillard, 2015） よくあるエラー エラーからの回復を助ける（Carroll et al., 1987） 経験者ショートカット 専門性逆転効果への対応（Kalyuga et al., 2003）

16. 1ステップの書き方（実例） ステップ1：Pythonが入っているか確認する 目的：スクリプトを動かすには、Pythonが必要です。まず入っているかを確認します。 なぜ：バージョンが古いと、この後の手順でエラーになることがあるためです。 $ python3 --version 期待される出力（例）： Python 3.12.4 確認：「Python 3.」から始まる行が出れば成功です。 違ったら：command not found の場合は未インストールです。「よくあるエラー」を見てください。 「なぜ」を一文加えるのは自己説明効果（Chi et al., 1989）を意識した工夫。

17. よくある失敗と対策 失敗 対策（根拠） 説明が長すぎて読まれない 最小限マニュアルの原則（Carroll et al., 1987） コード例が動かない・古い 実際に動作確認する（Aghajani et al., 2020） エラー時の対処が書いていない エラー回復を前提に設計する（Carroll et al., 1987） 初心者にも経験者にも同じ詳しさ ルートを分ける（Kalyuga et al., 2003） 新情報を一度に詰め込む 1ステップ1動作にする（Sweller, 1988） 公開前に誰にも読んでもらっていない 少人数でテストする（Nielsen & Landauer, 1993）

18. チェックリスト • 冒頭で完成イメージが伝わるか • 見出しの階層が飛んでいないか • 1ステップに新しい概念を詰め込みすぎていないか • コード例は実際に動作確認したか • 各ステップに「なぜ」「期待される出力」「確認方法」があるか • よくあるエラーが、症状・原因・対処の形で整理されているか • 経験者向けの近道（折りたたみ等）があるか • 公開前に、対象読者に近い人に読んでもらったか

19. 注意点・限界 • 紹介した研究の多くは1980〜2020年代の技術文書・ソフトウェア開発の場面を対象にしている。分野や ツールが変わると当てはまり方も変わり得る • ミニマリスト設計の実験は当時の紙マニュアルやヘルプ機能が対象で、現在のWeb上のREADMEにその まま当てはまるとは限らない • 専門性逆転効果（Kalyuga et al., 2003）は数学・科学分野の実験が中心で、プログラミング学習への一 般化は一部推論を含む • 「5人でテスト」の目安（Nielsen & Landauer, 1993）には、後年の研究で異論も出されている。あくま で目安として扱う • 効果の大きさや再現性は研究によって異なるため、断定は避け、自分の読者の反応で確かめながら使う

参考文献 • • Carroll, J. M., Smith-Kerker, P. L., Ford, J. R., & Mazur-Rimetz, S. A. (1987). The minimal manual. Human-Computer Interaction, 3(2), 123–153. van der Meij, H., & Carroll, J. M. (1998). Principles and heuristics for designing minimalist instruction. Technical Communic ation, 45(2), 243–261. • • Novick, D. G., & Ward, K. (2006). Why don't people read the manual? Proceedings of SIGDOC 2006, 11 –18. Sweller, J. (1988). Cognitive load during problem solving. Cognitive Science, 12(2), 257–285. • Sweller, J., & Cooper, G. A. (1985). The use of worked examples as a substitute for problem solving. Cognition and Instruction, 2(1), 59–89. • Atkinson, R. K., Derry, S. J., Renkl, A., & Wortham, D. (2000). Learning from examples. Review of Educational Research, 70(2) , 181–214. • Chi, M. T. H., Bassok, M., Lewis, M. W., Reimann, P., & Glaser, R. (1989). Self-explanations. Cognitive Science, 13(2), 145–182. • Kalyuga, S., Ayres, P., Chandler, P., & Sweller, J. (2003). The expertise reversal effect. Educational Psychologist, 38(1), 2 3–31. • Lorch, R. F. (1989). Text-signaling devices and their effects on reading and memory processes. Educational Psychology Review, 1(3), 209–234. • • Ko, A. J., Myers, B. A., & Aung, H. H. (2004). Six learning barriers in end-user programming systems. Proc. IEEE VL/HCC 2004, 199–206. van der Meij, H., & van der Meij, J. (2014). A comparison of paper-based and video tutorials for software learning. Computers & Education, 78, 150–159. • • Aghajani, E., et al. (2020). Software documentation: The practitioners' perspective. Proc. ICSE 2020, 590–601. Meng, M., Steinhardt, S., & Schubert, A. (2018). API documentation: What do software developers want? Journal of Technical Writing and Communication, 48(3), 295–330. • Uddin, G., & Robillard, M. P. (2015). How API documentation fails. IEEE Software, 32(4), 68–75. • • Prana, G. A. A., et al. (2019). Categorizing the content of GitHub README files. Empirical Software Engineering, 24(3), 1296 –1327. Nielsen, J., & Landauer, T. K. (1993). A mathematical model of the finding of usability problems. Proc. CHI 1993, 206–213. ※公開前にDOI・原文で書誌情報を確認してください。会議録（ICSE, CHI, SIGDOC, VL/HCC等）は特に確認を推奨します。