2023年3月24日のNTT Tech Conference 2023で発表した「エンジニアのためのドキュメントライティング - Docs for Developers」の講演資料です。
講演詳細については次のイベントページをご覧ください。 https://ntt-developers.github.io/ntt-tech-conference/2023/
エンジニアのためのドキュメントライティングNTT Tech Conference 2023(資料は別途公開)2023年3月NTT コミュニケーションズ 岩瀬 / @iwashi86
View Slide
1● エンジニアであれば「ドキュメントを書いておけば良かった」と思った経験はあるのでは？● 一方で「そもそも、ドキュメントの書き方を体系的に学んだことがない」という方も多いはず● 本トークは上記を学ぶための一助としていくつかのトピックを紹介本日の対象者
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」で重要なポイントを理解しているこちらがベース→
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」で重要なポイントを理解している○ パラグラフライティングの基礎について知っているこちらがベース→
5● 岩瀬 義昌 (@iwashi86) / Yoshimasa Iwase● 本業○ NTTコムでプロダクトマネジメントやアジャイル開発の全社支援○ その他、組織を強くすることなら何でも● サイドワーク○ 翻訳者○ AIスタートアップで Co-VPoE として組織支援○ 非常勤講師○ ポッドキャスター (fukabori.fm)
6本題
今日のアジェンダ● ドキュメントのライフサイクル● 特に意識しておきたい箇所○ 読み手の理解 および 読み方○ パラグラフライティング● （時間があれば落穂拾い）
ドキュメントのライフサイクル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章 ドキュメントの保守と非推奨化ユーザーを理解してジャーニーを描くジャーニーの中でドキュメントがこう役立つのではという仮説を立てる仮説検証のために実装（＝ドキュメント実装）設計してコードを書いてレビューするのと一緒プロダクト開発と同じ流れ
PART Iドキュメント作成の準備1章 読み手の理解2章 ドキュメントの計画PARTⅡドキュメントの作成3章 ドキュメントのドラフト4章 ドキュメントの編集5章 サンプルコードの組み込み6章 ビジュアルコンテンツの追加PARTⅢドキュメントの公開と運用7章 ドキュメントの公開8章 フィードバックの収集と組み込み9章 ドキュメントの品質測定10章 ドキュメントの構成11章 ドキュメントの保守と非推奨化ユーザーを理解してジャーニーを描くジャーニーの中でドキュメントがこう役立つのではという仮説を立てる仮説検証のために実装（＝ドキュメント実装）設計してコードを書いてレビューするのと一緒リリースして反応を見るユーザーからフィードバックを集めプロダクトを改善する不要な機能※は減らす※ ドキュメントはプロダクトの機能の1部プロダクト開発と同じ流れ
16● エンジニアがよく作る・利用するドキュメントに集中した書籍“エンジニアのためのドキュメントライティング” 本の補足・注意点
17“エンジニアのためのドキュメントライティング” 本の補足・注意点● エンジニアがよく作る・利用するドキュメントに集中した書籍○ そのため、ロジカルライティングやパラグラフライティングは説明されていない○ ドキュメントの種類のうちコンセプトガイド等ではロジカルシンキングが効果的
18● エンジニアがよく作る・利用するドキュメントに集中した書籍○ そのため、ロジカルライティングやパラグラフライティングは説明されていない○ ドキュメントの種類のうちコンセプトガイド等ではロジカルシンキングが効果的○ そこで、本資料後半で説明“エンジニアのためのドキュメントライティング” 本の補足・注意点
ドキュメントを書く上で最も大事なこと
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ○ ドキュメントにより、どんな課題を解きたいのか？
ドキュメントを書く上で最も大事なこと● 読み手となるユーザーを理解すること○ ユーザーは誰なのか？○ ユーザーは何を達成したいのか？■ ユーザーはドキュメントが読みたいのではなく目の前にある課題やニーズを解決したいだけ○ ドキュメントにより、どんな課題を解きたいのか？● なぜか？○ ユーザーの理解を外すと無価値なドキュメントが爆誕する
それ、ビルドトラップの兆候かも？“【資料公開】プロダクトマネジメントの ”罠”を回避しよう より” 引用, https://www.ryuzee.com/contents/blog/14556
どうすればユーザーを理解できるのか？
どうすればユーザーを理解できるのか？チャットでの会話ログプロダクトの設計メモインタビューメモ過去のメールコミットログ他にも色々
どうすればユーザーを理解できるのか？チャットでの会話ログプロダクトの設計メモインタビューメモ過去のメールコミットログ他にも色々ユーザーがプロダクトを使って成し遂げたいことは？ユーザーは誰か？（ここでも仮説）
検証：そのユーザー理解はあっているのか？
検証：そのユーザー理解はあっているのか？● ユーザーの理解を検証する最強の方法○ ユーザーと直接対話してみること
検証：そのユーザー理解はあっているのか？● ユーザーの理解を検証する最強の方法○ ユーザーと直接対話してみること● どうやって直接対話するか？○ 既存チャネルがあればそれを活用（例：カスタマーサクセス）○ サポートチケット○ インタビュー○ アンケート
対話したら知見をまとめていく● 代表的なまとめ方○ ユーザーペルソナ○ ユーザーストーリー○ ユーザージャーニーマップ（カスタマージャーニーマップ）
対話したら知見をまとめていく● 代表的なまとめ方○ ユーザーペルソナ○ ユーザーストーリー○ ユーザージャーニーマップ（カスタマージャーニーマップ）● なぜまとめておくのか？○ すぐに忘れてしまうため（覚えておけない）
ユーザーペルソナの例 (chatGPTのペルソナ)
ユーザーストーリーの例
ユーザージャーニーマップの例
ユーザージャーニーマップの例感情の起伏ラインを書くことも
🚨知識の呪い (認知バイアス)
🚨知識の呪い (認知バイアス)● こんな経験は？○ 同僚が、耳慣れない専門用語で話している○ 同僚が、開発環境を作る手順を教えてくれなかった○ デバッグでエラーメッセージを教えてくれたものの、他に必要な背景情報は伝えてくれなかった
🚨知識の呪い (認知バイアス)● こんな経験は？○ 同僚が、耳慣れない専門用語で話している○ 同僚が、開発環境を作る手順を教えてくれなかった○ デバッグでエラーメッセージを教えてくれたものの、他に必要な背景情報は伝えてくれなかった→ 悪気があったのではなく、 おそらく知っていると思っていて伝えていない（可能性が高い）
知識の呪いをどう断ち切るか？
知識の呪いをどう断ち切るか？● ユーザーへの共感が必要○ そのためにユーザーの理解をしてきた
知識の呪いをどう断ち切るか？● ユーザーへの共感が必要○ そのためにユーザーの理解をしてきた● フリクションログを作る○ フリクション = 原義は「摩擦」や「抵抗」■ 転じて、プロダクトを使う際に上手くつかえなかったことや違和感などを示す○ フリクションログはそれを記録したもの
フリクションログの例
余談：ドキュメントを書く上で最も難しいこととは？
余談：ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること（類義語？ → 発表スライドの表紙ができれば終わったようなもの）
余談：ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること● 手を進めるコツ○ 手に馴染んでいるツールを使うことドキュメント専用に新規に何かを学ばなくても良い○ 紙とペンでも、ホワイトボードでも何でも良い
余談：ドキュメントを書く上で最も難しいこととは？● 白紙から脱却すること ＝ 書き始めること● 手を進めるコツ○ 手に馴染んでいるツールを使うことドキュメント専用に新規に何かを学ばなくても良い○ 紙とペンでも、ホワイトボードでも何でも良いhttps://www.youtube.com/watch?v=JV3KOJ_Z4Vs
50こうして書き上げたドキュメントはどのように読まれるのか？
ドキュメントにまつわる真実● ユーザーは情報を探してドキュメントにたどり着く
ドキュメントにまつわる真実● ユーザーは情報を探してドキュメントにたどり着く● ユーザーは書いてある内容をほとんど読まない
ユーザーは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
https://docs.flutter.dev/development/ui/layout/building-adaptive-appsこの辺りがパラグラフ
パラグラフ● パラグラフに含まれるものは次のいずれか
パラグラフ● パラグラフに含まれるものは次のいずれか○ 1つの主張を概論的に述べた文（トピック・センテンス）
パラグラフ● パラグラフに含まれるものは次のいずれか○ 1つの主張を概論的に述べた文（トピック・センテンス）○ トピック・センテンスを具体的に、詳しく説明するもの（展開部の文）
パラグラフ● パラグラフに含まれるものは次のいずれか○ 1つの主張を概論的に述べた文（トピック・センテンス）○ トピック・センテンスを具体的に、詳しく説明するもの（展開部の文）○ そのパラグラフと他のパラグラフのつながりを示すもの
パラグラフ● パラグラフに含まれるものは次のいずれか○ 1つの主張を概論的に述べた文（トピック・センテンス）○ トピック・センテンスを具体的に、詳しく説明するもの（展開部の文）○ そのパラグラフと他のパラグラフのつながりを示すもの● トピック・センテンスと関係ない文や、反する文を含んでいけない
具体例A君は根っからのスポーツマンだ。夏は水泳、冬はスキー、春と秋はテニスと、日焼けのさめる間がない。いちばん年季を入れたのはスキーだという。
具体例の構造A君は根っからのスポーツマンだ。夏は水泳、冬はスキー、春と秋はテニスと、日焼けのさめる間がない。いちばん年季を入れたのはスキーだという。具体化して説明トピックセンテンス展開部の文
ある主張（伝えたいこと＝読者の課題を解決すること）1つのドキュメントはパラグラフが集まって構成されるこちらを参考に改変
ある主張（伝えたいこと＝読者の課題を解決すること）主張を説明するA 主張を説明するB 主張を説明するC1つのドキュメントはパラグラフが集まって構成される
ある主張（伝えたいこと＝読者の課題を解決すること）主張を説明するA 主張を説明するB 主張を説明するCBの具体内容① Bの具体内容②略 略1つのドキュメントはパラグラフが集まって構成される
Xという技術をチームで導入すべきだたとえば
Xという技術をチームで導入すべきだなぜならば現行のAは3年後にEoSとなるからたとえば注：説明上のサンプルなので、MECEではない
Xという技術をチームで導入すべきだなぜならば現行のAは3年後にEoSとなるからXは導入企業も多く、情報が世の中に多いからたとえば注：説明上のサンプルなので、MECEではない
Xという技術をチームで導入すべきだなぜならば現行のAは3年後にEoSとなるからXは導入企業も多く、情報が世の中に多いからXはBig Techが開発しており長く続く可能性が高いからたとえば注：説明上のサンプルなので、MECEではない
Xという技術をチームで導入すべきだなぜならば現行のAは3年後にEoSとなるからXは導入企業も多く、情報が世の中に多いからXはBig Techが開発しており長く続く可能性が高いからたとえば、SOにn件の情報がある略 略たとえば注：説明上のサンプルなので、MECEではない
Xという技術をチームで導入すべきだなぜならば現行のAは3年後にEoSとなるからXは導入企業も多く、情報が世の中に多いからXはBig Techが開発しており長く続く可能性が高いからたとえば、SOにn件の情報があるたとえば、GitHubのStar数がm件ある略 略たとえば注：説明上のサンプルなので、MECEではない
構造上の注意点（並列性）● 同階層の抽象度が異なると、理解が困難に + 議論が噛み合わなくなる
食べ物肉 魚構造上の注意点（並列性）● 同階層の抽象度が異なると、理解が困難に + 議論が噛み合わなくなる
食べ物肉 魚 バナナ構造上の注意点（並列性）● 同階層の抽象度が異なると、理解が困難に + 議論が噛み合わなくなる明らかに1つだけ具体的であり「これはなんだろう？？？」となる詳細が知りたい場合は←の書籍がおすすめ
どこまで書けばいいかは、読み手との関係・文脈依存
どこまで書けばいいかは、読み手との関係・文脈依存● 読み手との関係性が深いなら主張だけで事足りる可能性が高い○ 例： 一緒に働いて3年経ち、重要視すべき価値観があっている(とはいえ、意思決定の経緯を残すのは重要）不要かも
どこまで書けばいいかは、読み手との関係・文脈依存● 読み手との関係性が深いなら主張だけで事足りる可能性が高い○ 例： 一緒に働いて3年経ち、重要視すべき価値観があっている(とはいえ、意思決定の経緯を残すのは重要）● 反対に浅いなら全部説明したほうが次の行動へ繋がりやすい不要かも
トピック・センテンスと流し読みとの関係● トピック・センテンスを読んだ段階でパラグラフの主張が理解できる構成であれば「このパラグラフの残りは、これを説明したいんだな」として読み飛ばせる
トピック・センテンスと流し読みとの関係● トピック・センテンスを読んだ段階でパラグラフの主張が理解できる構成であれば「このパラグラフの残りは、これを説明したいんだな」として読み飛ばせる● 例：8.1 文は短く仕事の文書の文は、短く、短くと心がけて書くべきである。ある人は平均50字が目標だという。（以下、略）
86（時間があれば）落穂拾い
事実と意見をはっきり区別する● 手順書などのテクニカルドキュメントに意見は紛れこみにくい● 一方で設計の思想が現れるドキュメントは主観が入る○ ここで事実と意見が混ざると理解しやすさ・信憑性が低下する
事実と意見が曖昧な例“近頃の学生は整った文章を書く能力がないという声をよく聞くが，私はこれは主に理科系の学生に関していわれていることだと思う．理科系の学生がきちんとした文章を書けないことにふしぎはない．彼らの本領は文学ではないからである．”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
動詞に「方法」「こと」などを付けて安易に名詞化しない● 冗長な、くどい日本語になるため● 例：❌ 機能Aを使用するという方法もあります✅ 機能Aも使用できます❌ Bにより改善することができます✅ Bにより改善できますP.104こういう基礎的な部分がたくさんあるので良書をさっと読んでおくのがおすすめ
99ということで
今日お話ししたこと● ドキュメントのライフサイクル● 特に意識しておきたい箇所○ 読み手の理解 および 読み方○ パラグラフライティング● （時間があれば落穂拾い）
101ゴールのおさらい
今日のゴール (イベント終了時)● ドキュメントライティングのスキルが高まっている○ ドキュメントライティングの概要を知っている○ ドキュメントの「準備」で重要なポイントを理解している○ パラグラフライティングの基礎について知っているおしまい
Generative AI が全部駆逐するのでは？● 2023/3時点で、部分的にはYesっぽい○ 一方で、大規模に学習しているからかいまいちな日本語も生み出してくることがある（丁寧にプロンプトを書けば、かなり精度が上がる）
例https://atmarkit.itmedia.co.jp/ait/articles/1001/19/news106_2.html から例文引用“このコマンドの後には任意の値を設定することができる。このため、設定した値ごとに、システムの動作の確認を行わなければならない。この作業には時間がかかるため、テスト要員の追加が必要であると考えている。”
Generative AI が全部駆逐するのでは？● 2023/3時点で、部分的にはYesっぽい○ 一方で、大規模に学習しているからかいまいちな日本語も生み出してくることがある（丁寧にプロンプトを書けば、かなり精度が上がる）○ ただし、出力されたソースコードの安全性についてプログラマが見ないといけないのと一緒でしばらくは出力されたドキュメントを見ないといけなさそうおしまい
nttcom
k9i
cyberagentdevelopers
moyheen
tacck
banjun
skrb
yusuke0519
convto
line_developers
mode86
oracle4engineer
andpad
lara
malarkey
smashingmag
bermonpainter
marcelosomers
pauljervisheath
wjessup
paulrobertlloyd
hannesfritz
rasmusluckow
eileencodes
philhawksworth