2023年3月17日に開催されたイベント「エンジニアのためのドキュメントライティング - Forkwell Library #19」の登壇資料です。
イベントURL：https://forkwell.connpass.com/event/276576
エンジニアのためのドキュメントライティングForkwell Library #192023年3月@iwashi86
View Slide
1● エンジニアであれば「ドキュメントを書いておけば良かった」と思った経験はあるのでは？● 一方で「そもそも、ドキュメントの書き方を体系的に学んだことがない」という方も多いはず● 本書はそういう方向けの書籍であり、本イベントでその「一部※ + α」を紹介※ 特に訳者が重要だと考えている部分本日の想定対象者
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」「作成」「運用」で重要なポイントを理解している
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」「作成」「運用」で重要なポイントを理解している● （書籍でカバーされていないが抑えておくと良い）日本語文章で大事な点の一部および学びの資源を知っている
5● 岩瀬 義昌 (@iwashi86) / Yoshimasa Iwase● 本業○ 通信企業でプロダクトマネジメントやアジャイル開発の全社支援○ その他、組織を強くすることなら何でも● サイドワーク○ 翻訳者 (本イベントの書籍）○ ストックマーク Co-VPoE○ 非常勤講師○ ポッドキャスター (fukabori.fm)
6本題
今日のアジェンダ● 書籍の概要● 特に意識しておきたい箇所○ 読み手の理解（1章）○ ドラフトの執筆（3章）○ フィードバックの収集（8章）○ ドキュメントの品質測定（9章）● 時間があれば日本語特有の観点（+α）
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化赤字の部分は詳しめに後述します
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化● 1章：読み手であるユーザーを理解する（詳細後述）● 2章：ユーザーに提供すべきドキュメントタイプ計画する○ スタートガイド、チュートリアル、APIリファレンス、リリースノート、etc…○ プロダクト全体におけるユーザージャーニーに沿って作るドキュメントを計画する
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化● 3章：まずはドラフトを書く（後述）● 4章：編集を通じて精度を高める○ 例：どんな観点でレビューすべきか？（してもらうべきか？）● 5-6章：ユーザーの課題をより効果的に解決するために サンプルコードやビジュアルコンテンツ（図表・画像）を追加していく○ 例：どんな図表が効果的なのか？スクリーンショットはどう使えばいい？
書籍の構成PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化● 7-9章：ドキュメントを公開してフィードバックを得て プロダクトやドキュメントを改善する● 10章：ドキュメントがスケールしたら（量が増えたら）全体を構成し直す● 11章：ドキュメントが機能していない or/and 役目を果たしたら非推奨化して廃止する
プロダクト開発と同じ流れPART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化ユーザーを理解してジャーニーを描くジャーニーの中でドキュメントがこう役立つのではという仮説を立てる
PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化ユーザーを理解してジャーニーを描くジャーニーの中でドキュメントがこう役立つのではという仮説を立てる仮説検証のために実装（＝ドキュメント実装）設計してコードを書いてレビューするのと一緒プロダクト開発と同じ流れ
PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化ユーザーを理解してジャーニーを描くジャーニーの中でドキュメントがこう役立つのではという仮説を立てる仮説検証のために実装（＝ドキュメント実装）設計してコードを書いてレビューするのと一緒リリースして反応を見るユーザーからフィードバックを集めプロダクトを改善する不要な機能※は減らす※ ドキュメントはプロダクトの機能の1部プロダクト開発と同じ流れ
20書籍の補足・注意点● エンジニアがよく作る・利用するドキュメントに集中した書籍
21書籍の補足・注意点● エンジニアがよく作る・利用するドキュメントに集中した書籍○ そのため、ロジカルライティングやパラグラフライティングは説明されていない○ ドキュメントの種類のうちコンセプトガイド等ではロジカルシンキングが効果的
22書籍の補足・注意点● エンジニアがよく作る・利用するドキュメントに集中した書籍○ そのため、ロジカルライティングやパラグラフライティングは説明されていない○ ドキュメントの種類のうちコンセプトガイド等ではロジカルシンキングが効果的
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ○ ドキュメントにより、どんな課題を解きたいのか？
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ○ ドキュメントにより、どんな課題を解きたいのか？● なぜか？○ ユーザーの理解を外すと無価値なドキュメントが爆誕する
それ、ビルドトラップの兆候かも？“【資料公開】プロダクトマネジメントの ”罠”を回避しよう より” 引用, https://www.ryuzee.com/contents/blog/14556
どうすればユーザーを理解できるのか？
どうすればユーザーを理解できるのか？チャットでの会話ログプロダクトの設計メモインタビューメモ過去のメールコミットログ他にも色々
どうすればユーザーを理解できるのか？チャットでの会話ログプロダクトの設計メモインタビューメモ過去のメールコミットログ他にも色々ユーザーがプロダクトを使って成し遂げたいことは？ユーザーは誰か？（ここでも仮説）
検証：そのユーザー理解はあっているのか？
検証：そのユーザー理解はあっているのか？● ユーザーの理解を検証する最強の方法○ ユーザーと直接対話してみること
検証：そのユーザー理解はあっているのか？● ユーザーの理解を検証する最強の方法○ ユーザーと直接対話してみること● どうやって直接対話するか？○ 既存チャネルがあればそれを活用（例：カスタマーサクセス）○ サポートチケット○ インタビュー○ アンケート
対話したら知見をまとめていく● 代表的なまとめ方○ ユーザーペルソナ○ ユーザーストーリー○ ユーザージャーニーマップ（カスタマージャーニーマップ）
対話したら知見をまとめていく● 代表的なまとめ方○ ユーザーペルソナ○ ユーザーストーリー○ ユーザージャーニーマップ（カスタマージャーニーマップ）● なぜまとめておくのか？○ すぐに忘れてしまうため（覚えておけない）
ユーザーペルソナの例 (chatGPTのペルソナ)
ユーザーストーリーの例
ユーザージャーニーマップの例
ユーザージャーニーマップの例感情の起伏ラインを書くことも
🚨知識の呪い (認知バイアス)
🚨知識の呪い (認知バイアス)● こんな経験は？○ 同僚が、耳慣れない専門用語で話している○ 同僚が、開発環境を作る手順を教えてくれなかった○ デバッグでエラーメッセージを教えてくれたものの、他に必要な背景情報は伝えてくれなかった
🚨知識の呪い (認知バイアス)● こんな経験は？○ 同僚が、耳慣れない専門用語で話している○ 同僚が、開発環境を作る手順を教えてくれなかった○ デバッグでエラーメッセージを教えてくれたものの、他に必要な背景情報は伝えてくれなかった→ 悪気があったのではなく、 おそらく知っていると思っていて伝えていない（可能性が高い）
知識の呪いをどう断ち切るか？
知識の呪いをどう断ち切るか？● ユーザーへの共感が必要○ そのためにユーザーの理解をしてきた
知識の呪いをどう断ち切るか？● ユーザーへの共感が必要○ そのためにユーザーの理解をしてきた● フリクションログを作る○ フリクション = 原義は「摩擦」や「抵抗」■ 転じて、プロダクトを使う際に上手くつかえなかったことや違和感などを示す○ フリクションログはそれを記録したもの
フリクションログの例
49書籍の補足・注意点● 1章を通読するとストーリーや具体例などから「顧客へプロダクトを提供するときのドキュメントのみが対象？」「開発者向けのAPIの話？」と思うことがある
50書籍の補足・注意点● 1章を通読するとストーリーや具体例などから「顧客へプロダクトを提供するときのドキュメントのみが対象？」「開発者向けのAPIの話？」と思うことがある● 実際にはほとんどのドキュメントで応用可能○ 例えば「開発環境の構築手順書」であるなら「顧客(読み手) = 社内の開発者」となる
今日のアジェンダ● 書籍の概要● 特に意識しておきたい箇所○ 読み手の理解（1章）○ ドラフトの執筆（3章）○ フィードバックの収集と品質測定（8-9章）● 時間があれば日本語特有の観点（+α）
ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること
ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること● 手を進めるコツ○ 手に馴染んでいるツールを使うことドキュメント専用に新規に何かを学ばなくても良い○ 紙とペンでも、ホワイトボードでも何でも良い
ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること● 手を進めるコツ○ 手に馴染んでいるツールを使うことドキュメント専用に新規に何かを学ばなくても良い○ 紙とペンでも、ホワイトボードでも何でも良いhttps://www.youtube.com/watch?v=JV3KOJ_Z4Vs余談：書きやすくするためのスキルはありつつも、桜井さんの動画のとおり「いいからやる」のも重要だと思います。
ドラフトを書く上で最初に考えるべきこと● 冒頭で以下を整理する○ 「誰が」「何のために」読みにくるのか？○ 「どのタイプ」のドキュメントが適切か？
ドラフトを書く上で最初に考えるべきこと● 冒頭で以下を整理する○ 「誰が」「何のために」読みにくるのか？○ 「どのタイプ」のドキュメントが適切か？● 次にタイトルとアウトラインを決める○ タイトル = ドキュメントを読んで達成できるゴールの要約■ 例：カスタム会話型チャットボットの開発 など○ アウトライン = ゴールに必要な大まかな要素や手順■ 例：開発環境、API認証の方法 など
ユーザーと目的を整理したら肉付けする● 肉付けに使える要素○ 見出し○ 段落○ リスト○ コールアウト
ユーザーと目的を整理したら肉付けする● 肉付けに使える要素○ 見出し■ ドキュメント内の道しるべとして機能■ ユーザーに最も重要な情報を一番上に○ 段落○ リスト○ コールアウト
ユーザーと目的を整理したら肉付けする● 肉付けに使える要素○ 見出し○ 段落■ ドキュメントの詳細の理解に役立つ文章■ もっとも情報量が多いが、もっとも読むのが大変○ リスト○ コールアウト
ユーザーと目的を整理したら肉付けする● 肉付けに使える要素○ 見出し○ 段落○ リスト■ さっと読みやすい要素■ 順不同だが、重要順やアルファベット順でソートすると読みやすい○ コールアウト
ユーザーと目的を整理したら肉付けする● 肉付けに使える要素○ 見出し○ 段落○ リスト○ コールアウト（例）https://docs.flutter.dev/get-started/test-drive 文脈からは外れるが、ユーザーに伝えておきたいことを、目立つように書いているのがコールアウト
ドキュメントにまつわる真実● ユーザーは情報を探してドキュメントにたどり着く● ユーザーは書いてある内容をほとんど読まない
ユーザーはFパターンでドキュメントを読むhttps://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/
何がユーザーにとって大事か？● せっかく書いたから読んで欲しい● ユーザーが必要な情報をすばやく見つけられるのが一番良い○ そのために「流し読み」しやすい構成にする
どうすれば流し読みしやすくなるか？● 最も重要な情報を冒頭で述べる○ たとえば手順書であれば、手順書完了時点で達成できることを書く
https://docs.flutter.dev/development/ui/layout/tutorial冒頭で達成できることが書いてある
どうすれば流し読みしやすくなるか？● 最も重要な情報を冒頭で述べる○ たとえば手順書であれば、手順書完了時点で達成できることを書く● 大きな文章のかたまりを分割する○ 長い段落は流し読みが困難○ 見出し・リスト・サンプルコード・図表 で分割する
https://docs.flutter.dev/development/ui/layout/building-adaptive-apps段落と図表(実際は動画)で分割している例
どうすれば流し読みしやすくなるか？● 最も重要な情報を冒頭で述べる○ たとえば手順書であれば、手順書完了時点で達成できることを書く● 大きな文章のかたまりを分割する○ 長い段落は流し読みが困難○ 見出し・リスト・サンプルコード・図表 で分割する● 複数の方法が含まれているなら方法ごとに分割する○ 例：GUIを使うパターン、CUIを使うパターン
どうすれば流し読みしやすくなるか？● 最も重要な情報を冒頭で述べる○ たとえば手順書であれば、手順書完了時点で達成できることを書く● 大きな文章のかたまりを分割する○ 長い段落は流し読みが困難○ 見出し・リスト・サンプルコード・図表 で分割する（超重要。5章まるまるサンプルコードのみ。詳細は書籍にて）● 複数の方法が含まれているなら方法ごとに分割する○ 例：GUIを使うパターン、CUIを使うパターン
ドキュメントも仮説検証対象● プロダクトに開発した機能がユーザーに刺さるとは限らない○ 分からないので仮説検証する
ドキュメントも仮説検証対象● プロダクトに開発した機能がユーザーに刺さるとは限らない○ 分からないので仮説検証する● ドキュメントは、プロダクトの機能の一部○ 他機能と同様に「フィードバック(FB)」をベースに検証が必要→ FBをどうやって集めればいい？
ユーザーFBの集め方● フィードバックを受け取るための経路を用意する● 例○ ドキュメントのページへformなどを埋め込む
ユーザーFBの集め方● フィードバックを受け取るための経路を用意する● 例○ ドキュメントのページへformなどを埋め込む○ サポートチケットから読み取る
ユーザーFBの集め方● フィードバックを受け取るための経路を用意する● 例○ ドキュメントのページへformなどを埋め込む○ サポートチケットから読み取る○ ドキュメントに対する感情を集めるhttps://learn.microsoft.com/ja-jp/azure/virtual-machines/linux/quick-create-cli
ユーザーFBの集め方● フィードバックを受け取るための経路を用意する● 例○ ドキュメントのページへformなどを埋め込む○ サポートチケットから読み取る○ ドキュメントに対する感情を集める○ ユーザーサーベイを実施する
ユーザーFBの集め方● フィードバックを受け取るための経路を用意する● 例○ ドキュメントのページへformなどを埋め込む○ サポートチケットから読み取る○ ドキュメントに対する感情を集める○ ユーザーサーベイを実施する○ ユーザーコミュニティ(会)を作り、そこで質問する
ユーザーFBの活用方法● 集め始めると FB が大量※に蓄積される○ Quick Fixできるものから、詳細な検討が必要なものまで色々（※ FBに見せかけたサポート依頼や、バグ報告まで最初はなんでも混ざっている）
ユーザーFBの活用方法● 集め始めると FB が大量に蓄積される○ Quick Fixできるものから、詳細な検討が必要なものまで色々● そこで、そもそも有効なFBかどうか、また優先度をトリアージする○ その課題は有効か？○ その課題は修正可能か？（重複してない？再現可能？ など）○ どのぐらい重要か？
ユーザーFBの活用方法● 集め始めると FB が大量に蓄積される○ Quick Fixできるものから、詳細な検討が必要なものまで色々● そこで、そもそも有効なFBかどうか、また優先度をトリアージする○ その課題は有効か？○ その課題は修正可能か？（重複してない？再現可能？ など）○ どのぐらい重要か？→ kubernetes の例で見てみましょう！
https://www.kubernetes.dev/docs/guide/issue-triage/←次ページで この辺を拡大します
新規Issueの確認Issueを分類優先度付けhttps://www.kubernetes.dev/docs/guide/issue-triage/
https://www.kubernetes.dev/docs/guide/issue-triage/
https://www.kubernetes.dev/docs/guide/issue-triage/超重要あったらいいけどすぐやらないなるべく早くやる。できれば次のリリースで。長期的には重要たぶん有用だけどまだ十分な支持がない
87計測できないものは改善できないhttps://www.google.com/search?q=if+you+can%27t+measure+it+you+can%27t+improve+it&rlz=1C5CHFA_enJP997JP997&sxsrf=AJOqlzU-_y6qmLAx167G75myUrwYgWUsgw:1678984573101&source=lnms&tbm=isch&sa=X&ved=2ahUKEwi5mMD48OD9AhXPdHAKHUH-BfIQ_AUoAXoECAEQAw&biw=1678&bih=877&dpr=2
優れたドキュメントって何だろう？● ドキュメントの品質の定義「ドキュメントが優れているのは目的にかなっている場合である。」
優れたドキュメントって何だろう？● ドキュメントの品質の定義「ドキュメントが優れているのは目的にかなっている場合である。」ユーザーの特定の行動を促進すること + 組織のゴールを達成すること
ドキュメントの品質の構成要素● 機能品質○ ドキュメントの目的やゴールが達成されているか？
ドキュメントの品質の構成要素● 機能品質○ ドキュメントの目的やゴールが達成されているか？● 構造品質○ ドキュメント自体がうまく書かれているか？○ うまく構成されているか？
機能品質● アクセシビリティがあること● 目的があること● 見つけやすいこと● 正確なこと● 完全であること構造品質 (3C)● Clear (明確な)● Concise (簡潔な)● Consistent (一貫している)それぞれの詳細は書籍参照のこと
ドキュメントの品質の構成要素● 機能品質○ ドキュメントの目的やゴールが達成されているか？● 構造品質○ ドキュメント自体がうまく書かれているか？○ うまく構成されているか？さて、どちらの品質が重要でしょう？🤔
ドキュメントの品質の構成要素● 機能品質○ ドキュメントの目的やゴールが達成されているか？● 構造品質○ ドキュメント自体がうまく書かれているか？○ うまく構成されているか？さて、どちらの品質が重要でしょう？🤔→ 機能品質 ∵どれだけ最高の表現でもゴール達成しないと無価値
ドキュメントのメトリクス● Web解析ツールを使えば様々なメトリクスを測定可能○ PV数○ ユニークユーザー数○ 直帰率○ TTHW (Time to Hello World)○ etc…
ドキュメントのメトリクス● Web解析ツールを使えば様々なメトリクスを測定可能○ PV数○ ユニークユーザー数○ 直帰率○ TTHW (Time to Hello World)○ etc…● 使い切れないほどあるため、確認するメトリクスの絞り込みが重要
メトリクス活用のTips (の一部)● メトリクス活用の計画を作る○ なぜ測定したいのか？○ その情報を使って何をするのか？○ その努力で、どのように組織のゴールが前に進められるのか？
メトリクス活用のTips (の一部)● メトリクス活用の計画を作る○ なぜ測定したいのか？○ その情報を使って何をするのか？○ その努力で、どのように組織のゴールが前に進められるのか？● 基準値を確立する○ ベースラインがあれば何らかの変更の前後で比較可能になる（＝計測して基準値があるから改善できるようになる）
日本語の作文技術に関する書籍は多く存在タイトルが「ヘルプサイトの作り方」であるが作文技術が多く言及されている
事実と意見をはっきり区別する● 手順書などのテクニカルドキュメントに意見は紛れこみにくい● 一方で設計の思想が現れるドキュメントは主観が入る○ ここで事実と意見が混ざると理解しやすさ・信憑性が低下する
事実と意見が曖昧な例“近頃の学生は整った文章を書く能力がないという声をよく聞くが，私はこれは主に理科系の学生に関していわれていることだと思う．理科系の学生がきちんとした文章を書けないことにふしぎはない．彼らの本領は文学ではないからである．”1515/3419
“近頃の学生は整った文章を書く能力がないという声をよく聞くが，私はこれは主に理科系の学生に関していわれていることだと思う．理科系の学生がきちんとした文章を書けないことにふしぎはない．彼らの本領は文学ではないからである．”1515/3419意見事実と意見が曖昧な例
“近頃の学生は整った文章を書く能力がないという声をよく聞くが，私はこれは主に理科系の学生に関していわれていることだと思う．理科系の学生がきちんとした文章を書けないことにふしぎはない．彼らの本領は文学ではないからである．”1515/3419意見突然、事実になったため議論の土台がグラグラに事実と意見が曖昧な例
修飾の順序● 例：以下の紙を「言葉」で表現するhttps://unsplash.com/photos/WX5jK0BT5JQ白い厚手横線がある
修飾の順序● 節（述語を含む）を先に、句を後に 白い横線の引かれた厚手の紙 厚手の横線の引かれた白い紙 横線の引かれた厚手の白い紙P.43および70わかりやすい文はどれ？
修飾の順序● 節（述語を含む）を先に、句を後に❌ 白い横線の引かれた厚手の紙 （＝横線が白い ことになる）❌ 厚手の横線の引かれた白い紙 （＝横線が厚手 に捉えられる）✅ 横線の引かれた厚手の白い紙P.43および70述語がある
修飾の順序● 節（述語を含む）を先に、句を後に❌ 白い横線の引かれた厚手の紙 （＝横線が白い ことになる）❌ 厚手の横線の引かれた白い紙 （＝横線が厚手 に捉えられる）✅ 横線の引かれた厚手の白い紙● その他の原則○ 長い修飾句ほど先に、短いほどあとに○ 大状況から小状況へ、重大なものから重大でないものへ○ 親和度（なじみ）の強弱による配置転換P.43および70
動詞に「方法」「こと」などを付けて安易に名詞化しない● 冗長な、くどい日本語になるためP.104
動詞に「方法」「こと」などを付けて安易に名詞化しない● 冗長な、くどい日本語になるため● 例：❌ 機能Aを使用するという方法もあります✅ 機能Aも使用できますP.104
動詞に「方法」「こと」などを付けて安易に名詞化しない● 冗長な、くどい日本語になるため● 例：❌ 機能Aを使用するという方法もあります✅ 機能Aも使用できます❌ Bにより改善することができます✅ Bにより改善できますP.104と、いくつかの書籍から説明したように日本語の作文技術も学んでおくのがおすすめです
112ということで
今日お話ししたこと● 書籍の概要● 特に意識しておきたい箇所○ 読み手の理解（1章）○ ドラフトの執筆（3章）○ フィードバックの収集（8章）○ ドキュメントの品質測定（9章）● 時間があれば日本語特有の観点（+α）
今日お話ししたこと● 書籍の概要● 特に意識しておきたい箇所○ 読み手の理解（1章）○ ドラフトの執筆（3章）○ フィードバックの収集（8章）○ ドキュメントの品質測定（9章）● 時間があれば日本語特有の観点（+α） → 良書で補完！
120ゴールのおさらい
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」「作成」「運用」で重要なポイントを理解している● （書籍でカバーされていないが抑えておくと良い）日本語文章で大事な点を知っている
とはいえ、まだまだ話していない内容がたくさんある！● 良いサンプルコードってなんだろう？● 良いビジュアルコンテンツ、図表ってなんだろう？● 作ったとして、どうやってレビューすればいいんだろう？● 良いフィードバックって何だろう？● ドキュメントが増えてきたらどうやって全体構成すればいいんだろう？● ドキュメントの廃止（deprecate) ってどうやればいいんだろう？● etc…
● 良いサンプルコードってなんだろう？● 良いビジュアルコンテンツ、図表ってなんだろう？● 作ったとして、どうやってレビューすればいいんだろう？● 良いフィードバックって何だろう？● ドキュメントが増えてきたらどうやって全体構成すればいいんだろう？● ドキュメントの廃止（deprecate) ってどうやればいいんだろう？● etc…まだまだ話していない内容がたくさんある！書籍に全部書いてあります！よろしくお願いします！(おしまい)
iwashi86
trycycle
.png){kind=icon}
pharma_x_tech
miyake
k1low
lamrongol
hankehly
convto
mode86
tsutaj
taishin
okazuki
cyberagentdevelopers
ammeep
keathley
matthewcrist
trishagee
vanstee
robhawkes
brettharned
davidbonilla
geeforr
destraynor
bkeepers
smashingmag