ドキュメントと作成の基礎

勉強会として行なったドキュメントに関する研修資料

Transcript

1. ドキュメントの作成
2. 主なポイント 知識の呪い ドキュメントの作成手順 ビジュアルコンテンツについて ドキュメントの品質 目次
3. "Documentation is a love letter that you write to your future self." ~ドキュメントは未来の 自分へのラブレターだ~ Damian Conway
4. 知識の呪い
5. 知識の呪い = 認知のバイアス
6. 　 人間は他人が自分と同じ知識を 持っていると思い込んでいる 知識の呪い = 認知のバイアス
7. 知識の呪い 会話中の知らない専門用語 技術用語 業務用語 出力されたエラーメッセージの共有 環境・状況などの背景不足
8. → 知っていると思って伝えていない可能性が高い 知識の呪い 会話中の知らない専門用語 技術用語 業務用語 出力されたエラーメッセージの共有 環境・状況などの背景不足
9. 知識の呪いを断ち切る ユーザーへの共感が必要 　　→ユーザーの理解
10. 知識の呪いを断ち切る ユーザーへの共感が必要 　　→ユーザーの理解 ユーザーは誰か？ ユーザーのゴールは何か？
11. ユーザーはなぜドキュメントを読むのか？
12. ユーザーはなぜドキュメントを読むのか？ ドキュメントを読みたいわけではない
13. ユーザーはなぜドキュメントを読むのか？ ドキュメントを読みたいわけではない 問題を解決したいからドキュメントを読む
14. ユーザーを理解する ユーザーを理解する = ユーザーを定義する　　
15. ユーザーを理解する ユーザーを理解する = ユーザーを定義する　　 ユーザーを定義する方法 役割 開発者 プロダクトマネージャー
16. ユーザーを理解する ユーザーを理解する = ユーザーを定義する　　 ユーザーを定義する方法 役割 開発者 プロダクトマネージャー 経験レベル
17. ユーザーを理解する ユーザーを理解する = ユーザーを定義する　　 ユーザーを定義する方法 役割 開発者 プロダクトマネージャー 経験レベル ドキュメントを読んでいる状況
18. ユーザーを理解する 開発者 PdM 目的が違う
19. ユーザーを理解する 開発者 PdM 全てのユーザーのニーズが同じではない
20. ユーザーを理解する 開発者 PdM 全てのユーザーのニーズが同じではない ユーザー全てのニーズを満たすのは無理
21. ユーザーを理解する 開発者 PdM 全てのユーザーのニーズが同じではない ユーザー全てのニーズを満たすのは無理 最も重要なユーザーを優先する
22. 作成手順
23. ドキュメント 作成 レビュー 修正 公開 フィード バック
24. ドキュメント 作成 レビュー 修正 公開 フィード バック
25. ドキュメント作成で最も難しいこと
26. ドキュメント作成で最も難しいこと 白紙からの脱却 = 書き始めること コーディングも同じ
27. 手に馴染んだツールを使う 普段使っているエディタでいい ドキュメント専用に新規に学ばなくていい 紙とペン、ホワイトボードでもいい 脱却するためには
28. 手に馴染んだツールを使う 普段使っているエディタでいい ドキュメント専用に新規に学ばなくていい 紙とペン、ホワイトボードでもいい 脱却するためには
29. ドキュメント 作成 レビュー 修正 公開 フィード バック タイトルを決める アウトラインを作る ドラフトを書く
30. ドキュメントの以下を整理する ドラフトを書く前に 誰が、誰に 読み手 目的 ドキュメントのタイプ コンテンツパターン 何のための 誰に向けた何のためのドキュメントか? 誰が何のために読むドキュメントなのか? どのタイプのドキュメントが最適か?
31. 読み手、目的、コンテンツパターンが決定 タイトルを決める タイトルを決定できる タイトルの役割とは? ドキュメントを読んで達成できるゴールの要約 ドキュメントの目的を短くかつ明確に言い換えたフレーズに ドキュメントのゴールをタイトルからわかるように ドキュメントのゴールは1つに絞る →複数のゴールがあるなら複数のドキュメントが必要
32. アウトライン ゴール到達に必要な大まかな要素や手順 アウトラインを作る 必要なそうなものを順不同でリストアップ ゴール到達に必要な大まかな要素や手順って...?
33. アウトラインを作る
34. アウトラインを作る
35. アウトラインからドラフトを作成 ドラフトを書く
36. アウトラインからドラフトを作成 ドラフトを書く ドラフトの狙い アウトラインに記載したトピックを説明 読み手に必要な情報を各トピックに肉付け
37. 見出し 肉付けに使える要素 段落 リスト コールアウト
38. 見出し 肉付けに使える要素 段落 リスト コールアウト ドキュメント内の道しるべとして機能 ユーザーに最も重要な情報を一番上に 読み手に必要な情報へと正確に一気に辿り着けるように できる限り簡潔・明確・具体的に 重複のない見出しを使う 一貫性を保つ 見出しとスタイルを合わせる
39. 見出し 肉付けに使える要素 段落 リスト コールアウト ドキュメントの文脈・目的・詳細を理解 背景情報や仕組みに関する詳細を提供 複数の文のかたまり 最も情報量を多く含むが、読むのに時間がかかる 読み手の理解・行動に必要な背景情報を 短く保つ 段落内の文の数は、可能な限り5個以下に
40. 見出し 肉付けに使える要素 段落 リスト コールアウト 関連情報をさっと読みやすい形式にまとめられているもの 順序性はない 読み手の重要順やアルファベット順でソート →読みやすい リスト項目10個以上なら分割を検討 分割した場合はリスト間を見出しか段落で区切る
41. 見出し 肉付けに使える要素 段落 リスト コールアウト リストと同様な手順もある 望む結果を得るために、実行する一連の行動 手順には常に番号付きリストを使用 1つの手順は1つの行動を扱うように 複数の行動は、読み手の脱落に繋がる 手順が正常に完了したことを確認する方法を記載
42. 見出し 肉付けに使える要素 段落 リスト コールアウト 知っておくべきちょっとした情報であるが、 コンテンツの流れにそぐわない情報 警告・注意・ヒント 見逃すべきでない重要な情報にのみつける あまりに多いとユーザー疲れる
43. 見出し 段落 リスト コールアウト 肉付けに使える要素 コールアウトの例 (mdn Web Docs)
44. ドキュメントの矛盾した真実
45. ドキュメントの矛盾した真実 読み手は情報を探してドキュメントを読む
46. ドキュメントの矛盾した真実 読み手は情報を探してドキュメントを読む 読み手は書いてある内容をほとんど読まない
47. 読み手は書いてある内容をほとんど読まない →ほとんどの人が同じ読み方 欲しい回答が見つかるまでタイトルと見出しを流し読み →読む時のパターンは「F」 読み手の読み方
48. 最も重要な情報を冒頭で述べる 手順書であれば、手順完了で達成できることを書く 流し読みに適した書き方
49. 最も重要な情報を冒頭で述べる 手順書であれば、手順完了で達成できることを書く 大きな文章のかたまりを分割する 長い段落の流し読みは難しい → ユーザーは長い文章を見るとページを飛ばす 流し読みに適した書き方
50. 最も重要な情報を冒頭で述べる 手順書であれば、手順完了で達成できることを書く 大きな文章のかたまりを分割する 長い段落の流し読みは難しい → ユーザーは長い文章を見るとページを飛ばす 複数の長文ドキュメントを分割 GUI、CLIそれぞれの手順があるなら分割 流し読みに適した書き方
51. 完璧である必要はない ゴールは、読み手に情報を全て伝えること 最初のドラフト
52. 完璧である必要はない ゴールは、読み手に情報を全て伝えること 最初のドラフト コンテンツは完璧であるということを捨てる
53. 行き詰まりの回避 →他の人に助けを求める 　考えている問題と行き詰まっている箇所について話し合う 最初のドラフト
54. 行き詰まりの回避 →他の人に助けを求める 　考えている問題と行き詰まっている箇所について話し合う 最初のドラフト 足りないコンテンツ →コードのように[TODO]を残す 最初から順番通りに書こうとしない 書いている途中で足りないことに気づいたらメモを残す l →書きあげれるところから、書きやすいものから書く
55. 完成したかどうか判断する為に自分に問いかける →セルフレビュー ドラフトを完成させる
56. 完成したかどうか判断する為に自分に問いかける →セルフレビュー ドラフトを完成させる 大見出しはドキュメントのゴールを要約しているか 複数の見出しによって十分に要約されているか 最初から最後まで読み手のニーズに応えているか 情報の流れは読み手にとって理解しやすいものか ドキュメントパターンやテンプレートに従っているか
57. ドキュメント 作成 レビュー 修正 公開 フィード バック セルフレビュー ドキュメントの編集
58. コーディングと似ている ドキュメントの編集
59. 検証 コーディングと似ている テスト レビュー ドキュメントの編集
60. 一度に複数の観点を見ると進行が遅くなる →各観点で周回を行う 各観点で読む時、初見であるかのように読む ドキュメントの編集
61. 一度に複数の観点を見ると進行が遅くなる →各観点で周回を行う 各観点で読む時、初見であるかのように読む ドキュメントの編集 技術的な正確さ 完全性 構成 明確さと簡潔さ
62. 技術的な 正確さ 編集の観点 完全性 構成 明確さと 簡潔さ 指示通りに作業すれば、約束した結果が得られるか 手順の場合は実行する 技術的な専門用語、混乱しやすい単語はあるか 技術的なコンセプトの説明の場合、 ユーザーに必要なレベルで説明できているか 用語の不一致がある場合は一貫するように 　　　 例)暗号化とハッシュ化が同じ意味で使われている
63. 技術的な 正確さ 編集の観点 完全性 構成 明確さと 簡潔さ TODOやTDBが残っていないか 情報の有効期限等の制約があるなら明記されているか 特定のバージョンの制約があるなら明記されているか
64. 技術的な 正確さ 編集の観点 完全性 構成 明確さと 簡潔さ タイトルと見出しから、何について書かれたか明確か 一貫性のある、論理的な構成方法で構成されているか 他のドキュメントにおくべきセクションはないか テンプレートに従って書かれているか(存在する場合) 前提とする手順がある場合は明記 〇〇の設定が完了している前提・管理者権限が必要等 ドキュメントの最初に読まれるのはタイトル・見出し・目次 これらの道標が正しいかの確認
65. 技術的な 正確さ 完全性 構成 明確さと 簡潔さ 一文と段落が簡単に理解できるか一行ずつレビュー 不自然な表現の書き換え 重複項目の削除 不要な言葉を取り除く 編集の観点
66. 技術的な 正確さ 完全性 構成 明確さと 簡潔さ 一文と段落が簡単に理解できるか一行ずつレビュー 不自然な表現の書き換え 重複項目の削除 不要な言葉を取り除く 編集の観点 ドキュメントに対するリファクタリング
67. 技術的な 正確さ 完全性 構成 明確さと 簡潔さ できるだけ明確になっているか 一貫して使われてない単語で、訂正が必要なもの 削除しても良い、不要な単語や表現があるか 読み手が戸惑うような熟語・比喩・スラングがあるか 避けるべき偏った言葉は使われていないか 編集の観点
68. ドキュメント 作成 レビュー 修正 公開 フィード バック 編集プロセス セルフレビュー ピアレビュー テクニカルレビュー フィードバックの取入
69. コードレビューのプロセスと同じ 編集プロセス セルフレビュー レビュー依頼 技術レビュー依頼 (必要があれば)
70. コードレビューのプロセスと同じ 編集プロセス セルフレビュー レビュー依頼 技術レビュー依頼 (必要があれば)
71. セルフレビューのチェックリストの例 書いている内容によってチェックリストは変わる 編集用チェックリスト タイトルが短くて具体的である 見出しは論理的に並べており、一貫性がある ドキュメントの目的が最初段落で説明されている 手順はテストされていて動作する テンプレート構成に従っている リンクが全て有効である 誤字脱字・文法がチェックされている グラフィックや画像が定義されている 前提条件や次のステップが定義されている
72. コードレビューのプロセスと同じ 編集プロセス セルフレビュー レビュー依頼 技術レビュー依頼 (必要があれば)
73. レビュー依頼時にレビュワーに求めている フィードバックの種類を伝える 構成について 技術面 明確さと簡潔さ ピアレビュー
74. レビュー依頼時にレビュワーに求めている フィードバックの種類を伝える 構成について 技術面 明確さと簡潔さ レビュー方法も明確にする インラインコメントを使用 サイドバーのメモ 紙でマークしていく ピアレビュー
75. コードレビューのプロセスと同じ 編集プロセス セルフレビュー レビュー依頼 技術レビュー依頼 (必要があれば)
76. トピックの技術的な専門家に確認や追記をもらう ドメインエキスパート その他分野のエキスパート 1人で全ての専門知識を網羅するのは不可能なため テクニカルレビュー
77. 貰ったフィードバックを確認し取り入れるか検討する 必ずしも取り入れる必要はない 有効や必要であるとも限らない レビュワーの懸念点を理解するために、 すべてのフィードバックをレビューすることが大切 フィードバックを貰って取り入れる
78. ドキュメント 作成 レビュー 修正 公開 フィード バック 外部へのフィードバックは特殊 今は社内向けの想定のため割愛
79. ビジュアルコンテンツに ついて
80. ビジュアルコンテンツ = 写真・映像 ビジュアルコンテンツについて
81. ビジュアルコンテンツ = 写真・映像 アメリカのことわざ 「１枚の絵は1000の言葉に値する」 （a picture is worth a thousand words） ビジュアルコンテンツについて
82. ビジュアルコンテンツ = 写真・映像 アメリカのことわざ 「１枚の絵は1000の言葉に値する」 （a picture is worth a thousand words） 日本だと「百聞は一見にしかず」 ビジュアルコンテンツについて
83. ビジュアルコンテンツ = 写真・映像 アメリカのことわざ 「１枚の絵は1000の言葉に値する」 （a picture is worth a thousand words） 日本だと「百聞は一見にしかず」 1000単語読むのにかかる時間はどれくらい? ビジュアルコンテンツについて
84. ビジュアルコンテンツ = 写真・映像 アメリカのことわざ 「１枚の絵は1000の言葉に値する」 （a picture is worth a thousand words） 日本だと「百聞は一見にしかず」 1000単語読むのにかかる時間はどれくらい? ビジュアルコンテンツについて 人間の脳は画像であれば13ミリ秒で処理
85. イラストを含む指示とイラストを含まない指示に別れて実験 イラストを含む指示に従った読み手は、 含まない指示に従った読み手により 32%良い成績で指示を完了 ビジュアルコンテンツについて
86. ビジュアルコンテンツはただ便利ではない ハイリスクハイリターン
87. 効果的なビジュアルコンテンツは有効に働く ビジュアルコンテンツはあくまで補助 ドキュメントの代替ではない 作成は難しい 効果のないビジュアルコンテンツは情報の伝達を妨げる
88. 次の点が欠けていると効果のないコンテンツになりやすい 理解容易性 アクセシビリティ パフォーマンス 作成は難しい
89. 情報に関連している画像を読み手は注視する どんなに美しいデザインであっても、他の画像は無視される 理解容易性
90. 情報に関連している画像を読み手は注視する どんなに美しいデザインであっても、他の画像は無視される 理解容易性 デザインの美しさが重要な役割を果たさないのか?
91. 情報に関連している画像を読み手は注視する どんなに美しいデザインであっても、他の画像は無視される 理解容易性 デザインの美しさが重要な役割を果たさないのか?
92. 情報に関連している画像を読み手は注視する どんなに美しいデザインであっても、他の画像は無視される 理解容易性 デザインの美しさが重要な役割を果たさないのか? 見た目の悪さによって読み手はコンテンツへの興味を失う
93. 矢印が交差している ラベルが不足している 抽象化のレイヤーが異なってる 理解容易性 ごちゃごちゃしている図 混乱するだけでなく興味も失うので悪い図は邪魔
95. ビジュアルコンテンツの提供方法を考える必要がある 読み込み速度に影響がある 読み込み時間があまりに長いと離脱する パフォーマンス
96. 特にUIを見てもらいたい場合は、スクリーショットは有用 利用が役立ちそうだなと考えたら次のようにする スクリーンショットの利用 文章中からの参照もしくは説明と一緒に表示されること 説明や関連する文章の近くで表示されること つまり綺麗で散らかっていないこと UI以外をスクリーンショットに含めないこと 十分な背景情報と共にUIの関連部分が含まれていること 大きすぎないこと 画面のすべての部分が読み込める必要がある 小さすぎないこと 読み手が体験しているUIと読み手が関連付けできる必要がある
97. スクリーンショットに注釈をつけて、 画像の一部に注目してもらうと有効になることがある ブロックや矢印によって、イメージの一部を強調できる 他の部分をグレーアウトすることで、 目立たないようにすることもできる スクリーンショットの利用
98. スクリーンショットに注釈をつけて、 画像の一部に注目してもらうと有効になることがある ブロックや矢印によって、イメージの一部を強調できる 他の部分をグレーアウトすることで、 目立たないようにすることもできる スクリーンショットの利用 使わない方がいいもの IPアドレスやサンプルコード 　→コピーする場合があるため
99. ドキュメントで役にたつプロセス図 ボックスと矢印 フローチャート スイムレーン 図の種類
100. ドキュメントで役にたつプロセス図 ボックスと矢印 フローチャート スイムレーン 図の種類 普段使っていると思うので割愛
101. 複数のコントリビューター、アクターがいる状況を表すとき プロセスを最初から最後まで表現 サンプル) スイムレーン
102. どの種類の図を選んだとしても、目的は単純化 1枚の図につき、アイデアを1つだけ書くようにする 図の描写
104. 映像コンテンツの作成はより難しい 映像の修正よりも画像の修正の方がはるかに簡単 映像の再撮影、再公開するための準備ができるか 映像コンテンツ
105. どんなに文字が少なくてもコンテンツではある レビュー レビューが必要
106. どんなに文字が少なくてもコンテンツではある レビュー レビューが必要 理解容易性 アクセシビリティ パフォーマンスの要件 満たしているか
107. どんなに文字が少なくてもコンテンツではある レビュー レビューが必要 理解容易性 アクセシビリティ パフォーマンスの要件 満たしているか デザインは主観的である →知識の呪いがあることを思い出す
108. ほとんどのドキュメントの失敗の最大要因 レビュー
109. ほとんどのドキュメントの失敗の最大要因 レビュー 保守
110. ほとんどのドキュメントの失敗の最大要因 レビュー 文章はすぐに時代遅れになる 画像はさらに早く時代遅れになる →UIを1つでも変更したら古いもの プロセスの急な変更で誤った方向に導きかない 保守
111. ドキュメントの 品質測定
112. ドキュメントが優れているのは目的にかなっている場合 ドキュメントの品質 機能品質 構成品質
113. ドキュメントの目的・ゴールが達成されているかどうか 機能品質 アクセシビリティがあること 目的があること 見つけやすいこと 正確であること 完全であること
114. ドキュメント自体がうまく書かれているか うまく構成されているか 構造品質
115. Clear ドキュメント自体がうまく書かれているか うまく構成されているか 構造品質 3つのC Concise Consistent 明確な 簡潔な 一貫している
116. Clear ドキュメント自体がうまく書かれているか うまく構成されているか 構造品質 3つのC Concise Consistent 明確な 簡潔な 一貫している 構造品質と機能品質の両方あるべきだが、 機能品質の方がより重要
117. 今回は読みやすいドキュメントの構成部分 文章を書く能力(ライティングスキル)も必要
118. おわり