Upgrade to Pro — share decks privately, control downloads, hide ads and more …

エンジニアのためのドキュメントライティング / Docs for Developers

iwashi
March 17, 2023

エンジニアのためのドキュメントライティング / Docs for Developers

2023年3月17日に開催されたイベント「エンジニアのためのドキュメントライティング - Forkwell Library #19」の登壇資料です。

イベントURL:https://forkwell.connpass.com/event/276576

iwashi

March 17, 2023
Tweet

More Decks by iwashi

Other Decks in Technology

Transcript

  1. エンジニアのための
    ドキュメントライティング
    Forkwell Library #19
    2023年3月
    @iwashi86

    View Slide

  2. 1
    ● エンジニアであれば
    「ドキュメントを書いておけば良かった」
    と思った経験はあるのでは?
    ● 一方で
    「そもそも、ドキュメントの書き方を体系的に学んだことがない」
    という方も多いはず
    ● 本書はそういう方向けの書籍であり、本イベントでその「一部※ + α」を紹介
    ※ 特に訳者が重要だと考えている部分
    本日の想定対象者

    View Slide

  3. 今日のゴール (イベント終了時)
    ● ドキュメントライティングのスキルが高まっている

    View Slide

  4. 今日のゴール (イベント終了時)
    ● ドキュメントライティングのスキルが高まっている
    ○ ドキュメントライティングの概要を知っている
    ○ ドキュメントの「準備」「作成」「運用」で
    重要なポイントを理解している

    View Slide

  5. 今日のゴール (イベント終了時)
    ● ドキュメントライティングのスキルが高まっている
    ○ ドキュメントライティングの概要を知っている
    ○ ドキュメントの「準備」「作成」「運用」で
    重要なポイントを理解している
    ● (書籍でカバーされていないが抑えておくと良い)
    日本語文章で大事な点の一部および学びの資源を知っている

    View Slide

  6. 5
    ● 岩瀬 義昌 (@iwashi86) / Yoshimasa Iwase
    ● 本業
    ○ 通信企業でプロダクトマネジメントや
    アジャイル開発の全社支援
    ○ その他、組織を強くすることなら何でも
    ● サイドワーク
    ○ 翻訳者 (本イベントの書籍)
    ○ ストックマーク Co-VPoE
    ○ 非常勤講師
    ○ ポッドキャスター (fukabori.fm)

    View Slide

  7. 6
    本題

    View Slide

  8. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  9. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  10. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画

    View Slide

  11. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加

    View Slide

  12. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化

    View Slide

  13. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    赤字の部分は詳しめに後述します

    View Slide

  14. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ● 1章:読み手であるユーザーを理解する(詳細後述)
    ● 2章:ユーザーに提供すべきドキュメントタイプ計画する
    ○ スタートガイド、チュートリアル、APIリファレンス、リリースノート、etc…
    ○ プロダクト全体におけるユーザージャーニーに沿って作るドキュメントを計画する

    View Slide

  15. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ● 3章:まずはドラフトを書く(後述)
    ● 4章:編集を通じて精度を高める
    ○ 例:どんな観点でレビューすべきか?(してもらうべきか?)
    ● 5-6章:ユーザーの課題をより効果的に解決するために
        サンプルコードやビジュアルコンテンツ(図表・画像)を追加していく
    ○ 例:どんな図表が効果的なのか?スクリーンショットはどう使えばいい?

    View Slide

  16. 書籍の構成
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ● 7-9章:ドキュメントを公開してフィードバックを得て
        プロダクトやドキュメントを改善する
    ● 10章:ドキュメントがスケールしたら(量が増えたら)全体を構成し直す
    ● 11章:ドキュメントが機能していない or/and 役目を果たしたら非推奨化して廃止する

    View Slide

  17. プロダクト開発と同じ流れ
    PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ユーザーを理解して
    ジャーニーを描く
    ジャーニーの中で
    ドキュメントが
    こう役立つのでは
    という仮説を立てる

    View Slide

  18. PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ユーザーを理解して
    ジャーニーを描く
    ジャーニーの中で
    ドキュメントが
    こう役立つのでは
    という仮説を立てる
    仮説検証のために実装
    (=ドキュメント実装)
    設計してコードを書いて
    レビューするのと一緒
    プロダクト開発と同じ流れ

    View Slide

  19. PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ユーザーを理解して
    ジャーニーを描く
    ジャーニーの中で
    ドキュメントが
    こう役立つのでは
    という仮説を立てる
    仮説検証のために実装
    (=ドキュメント実装)
    設計してコードを書いて
    レビューするのと一緒
    リリースして反応を見る
    ユーザーから
    フィードバックを集め
    プロダクトを改善する
    不要な機能※は減らす
    ※ ドキュメントはプロダクトの機能の1部
    プロダクト開発と同じ流れ

    View Slide

  20. PART I
    ドキュメント作成の準備
    1章 読み手の理解
    2章 ドキュメントの計画
    PARTⅡ
    ドキュメントの作成
    3章 ドキュメントのドラフト
    4章 ドキュメントの編集
    5章 サンプルコードの組み込み
    6章 ビジュアルコンテンツの追加
    PARTⅢ
    ドキュメントの公開と運用
    7章 ドキュメントの公開
    8章 フィードバックの収集と組み込み
    9章 ドキュメントの品質測定
    10章 ドキュメントの構成
    11章 ドキュメントの保守と非推奨化
    ユーザーを理解して
    ジャーニーを描く
    ジャーニーの中で
    ドキュメントが
    こう役立つのでは
    という仮説を立てる
    仮説検証のために実装
    (=ドキュメント実装)
    設計してコードを書いて
    レビューするのと一緒
    リリースして反応を見る
    ユーザーから
    フィードバックを集め
    プロダクトを改善する
    不要な機能※は減らす
    ※ ドキュメントはプロダクトの機能の1部
    プロダクト開発と同じ流れ

    View Slide

  21. 20
    書籍の補足・注意点
    ● エンジニアがよく作る・利用するドキュメントに集中した書籍

    View Slide

  22. 21
    書籍の補足・注意点
    ● エンジニアがよく作る・利用するドキュメントに集中した書籍
    ○ そのため、ロジカルライティングや
    パラグラフライティングは説明されていない
    ○ ドキュメントの種類のうち
    コンセプトガイド等では
    ロジカルシンキングが効果的

    View Slide

  23. 22
    書籍の補足・注意点
    ● エンジニアがよく作る・利用するドキュメントに集中した書籍
    ○ そのため、ロジカルライティングや
    パラグラフライティングは説明されていない
    ○ ドキュメントの種類のうち
    コンセプトガイド等では
    ロジカルシンキングが効果的

    View Slide

  24. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  25. ドキュメントを書く上で最も大事なこと
    ● 読み手となるユーザーを理解すること

    View Slide

  26. ドキュメントを書く上で最も大事なこと
    ● 読み手となるユーザーを理解すること
    ○ ユーザーは誰なのか?

    View Slide

  27. ドキュメントを書く上で最も大事なこと
    ● 読み手となるユーザーを理解すること
    ○ ユーザーは誰なのか?
    ○ ユーザーは何を達成したいのか?
    ■ ユーザーはドキュメントが読みたいのではなく
    目の前にある課題やニーズを解決したいだけ

    View Slide

  28. ドキュメントを書く上で最も大事なこと
    ● 読み手となるユーザーを理解すること
    ○ ユーザーは誰なのか?
    ○ ユーザーは何を達成したいのか?
    ■ ユーザーはドキュメントが読みたいのではなく
    目の前にある課題やニーズを解決したいだけ
    ○ ドキュメントにより、どんな課題を解きたいのか?

    View Slide

  29. ドキュメントを書く上で最も大事なこと
    ● 読み手となるユーザーを理解すること
    ○ ユーザーは誰なのか?
    ○ ユーザーは何を達成したいのか?
    ■ ユーザーはドキュメントが読みたいのではなく
    目の前にある課題やニーズを解決したいだけ
    ○ ドキュメントにより、どんな課題を解きたいのか?
    ● なぜか?
    ○ ユーザーの理解を外すと無価値なドキュメントが爆誕する

    View Slide

  30. それ、ビルドトラップの兆候かも?
    “【資料公開】プロダクトマネジメントの ”罠”を回避しよう より” 引用, https://www.ryuzee.com/contents/blog/14556

    View Slide

  31. どうすればユーザーを理解できるのか?

    View Slide

  32. どうすればユーザーを理解できるのか?
    チャットでの会話ログ
    プロダクトの設計メモ
    インタビューメモ
    過去のメール
    コミットログ
    他にも色々

    View Slide

  33. どうすればユーザーを理解できるのか?
    チャットでの会話ログ
    プロダクトの設計メモ
    インタビューメモ
    過去のメール
    コミットログ
    他にも色々
    ユーザーがプロダクトを
    使って成し遂げたいことは?
    ユーザーは誰か?
    (ここでも仮説)

    View Slide

  34. 検証:そのユーザー理解はあっているのか?

    View Slide

  35. 検証:そのユーザー理解はあっているのか?
    ● ユーザーの理解を検証する最強の方法
    ○ ユーザーと直接対話してみること

    View Slide

  36. 検証:そのユーザー理解はあっているのか?
    ● ユーザーの理解を検証する最強の方法
    ○ ユーザーと直接対話してみること
    ● どうやって直接対話するか?
    ○ 既存チャネルがあればそれを活用(例:カスタマーサクセス)
    ○ サポートチケット
    ○ インタビュー
    ○ アンケート

    View Slide

  37. 対話したら知見をまとめていく
    ● 代表的なまとめ方
    ○ ユーザーペルソナ
    ○ ユーザーストーリー
    ○ ユーザージャーニーマップ(カスタマージャーニーマップ)

    View Slide

  38. 対話したら知見をまとめていく
    ● 代表的なまとめ方
    ○ ユーザーペルソナ
    ○ ユーザーストーリー
    ○ ユーザージャーニーマップ(カスタマージャーニーマップ)
    ● なぜまとめておくのか?
    ○ すぐに忘れてしまうため(覚えておけない)

    View Slide

  39. ユーザーペルソナの例 (chatGPTのペルソナ)

    View Slide

  40. ユーザーストーリーの例

    View Slide

  41. ユーザージャーニーマップの例

    View Slide

  42. ユーザージャーニーマップの例
    感情の起伏
    ラインを
    書くことも

    View Slide

  43. 🚨知識の呪い (認知バイアス)

    View Slide

  44. 🚨知識の呪い (認知バイアス)
    ● こんな経験は?
    ○ 同僚が、耳慣れない専門用語で話している
    ○ 同僚が、開発環境を作る手順を教えてくれなかった
    ○ デバッグでエラーメッセージを教えてくれたものの、
    他に必要な背景情報は伝えてくれなかった

    View Slide

  45. 🚨知識の呪い (認知バイアス)
    ● こんな経験は?
    ○ 同僚が、耳慣れない専門用語で話している
    ○ 同僚が、開発環境を作る手順を教えてくれなかった
    ○ デバッグでエラーメッセージを教えてくれたものの、
    他に必要な背景情報は伝えてくれなかった
    → 悪気があったのではなく、
      おそらく知っていると思っていて伝えていない(可能性が高い)

    View Slide

  46. 知識の呪いをどう断ち切るか?

    View Slide

  47. 知識の呪いをどう断ち切るか?
    ● ユーザーへの共感が必要
    ○ そのためにユーザーの理解をしてきた

    View Slide

  48. 知識の呪いをどう断ち切るか?
    ● ユーザーへの共感が必要
    ○ そのためにユーザーの理解をしてきた
    ● フリクションログを作る
    ○ フリクション = 原義は「摩擦」や「抵抗」
    ■ 転じて、プロダクトを使う際に
    上手くつかえなかったことや違和感などを示す
    ○ フリクションログはそれを記録したもの

    View Slide

  49. フリクションログの例

    View Slide

  50. 49
    書籍の補足・注意点
    ● 1章を通読するとストーリーや具体例などから
    「顧客へプロダクトを提供するときのドキュメントのみが対象?」
    「開発者向けのAPIの話?」
    と思うことがある

    View Slide

  51. 50
    書籍の補足・注意点
    ● 1章を通読するとストーリーや具体例などから
    「顧客へプロダクトを提供するときのドキュメントのみが対象?」
    「開発者向けのAPIの話?」
    と思うことがある
    ● 実際にはほとんどのドキュメントで応用可能
    ○ 例えば「開発環境の構築手順書」であるなら
    「顧客(読み手) = 社内の開発者」となる

    View Slide

  52. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集と品質測定(8-9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  53. ドキュメントを書く上で最も難しいこととは?
    ● 白紙から脱却すること = 書き始めること

    View Slide

  54. ドキュメントを書く上で最も難しいこととは?
    ● 白紙から脱却すること = 書き始めること
    ● 手を進めるコツ
    ○ 手に馴染んでいるツールを使うこと
    ドキュメント専用に新規に何かを学ばなくても良い
    ○ 紙とペンでも、ホワイトボードでも何でも良い

    View Slide

  55. ドキュメントを書く上で最も難しいこととは?
    ● 白紙から脱却すること = 書き始めること
    ● 手を進めるコツ
    ○ 手に馴染んでいるツールを使うこと
    ドキュメント専用に新規に何かを学ばなくても良い
    ○ 紙とペンでも、ホワイトボードでも何でも良い
    https://www.youtube.com/watch?v=JV3KOJ_Z4Vs
    余談:書きやすくするためのスキルはありつつも、桜井さんの動画のとおり「いいからやる」のも重要だと思います。

    View Slide

  56. ドラフトを書く上で最初に考えるべきこと
    ● 冒頭で以下を整理する
    ○ 「誰が」「何のために」読みにくるのか?
    ○ 「どのタイプ」のドキュメントが適切か?

    View Slide

  57. ドラフトを書く上で最初に考えるべきこと
    ● 冒頭で以下を整理する
    ○ 「誰が」「何のために」読みにくるのか?
    ○ 「どのタイプ」のドキュメントが適切か?
    ● 次にタイトルとアウトラインを決める
    ○ タイトル = ドキュメントを読んで達成できるゴールの要約
    ■ 例:カスタム会話型チャットボットの開発 など
    ○ アウトライン = ゴールに必要な大まかな要素や手順
    ■ 例:開発環境、API認証の方法 など

    View Slide

  58. ユーザーと目的を整理したら肉付けする
    ● 肉付けに使える要素
    ○ 見出し
    ○ 段落
    ○ リスト
    ○ コールアウト

    View Slide

  59. ユーザーと目的を整理したら肉付けする
    ● 肉付けに使える要素
    ○ 見出し
    ■ ドキュメント内の道しるべとして機能
    ■ ユーザーに最も重要な情報を一番上に
    ○ 段落
    ○ リスト
    ○ コールアウト

    View Slide

  60. ユーザーと目的を整理したら肉付けする
    ● 肉付けに使える要素
    ○ 見出し
    ○ 段落
    ■ ドキュメントの詳細の理解に役立つ文章
    ■ もっとも情報量が多いが、もっとも読むのが大変
    ○ リスト
    ○ コールアウト

    View Slide

  61. ユーザーと目的を整理したら肉付けする
    ● 肉付けに使える要素
    ○ 見出し
    ○ 段落
    ○ リスト
    ■ さっと読みやすい要素
    ■ 順不同だが、重要順やアルファベット順でソートすると読みやすい
    ○ コールアウト

    View Slide

  62. ユーザーと目的を整理したら肉付けする
    ● 肉付けに使える要素
    ○ 見出し
    ○ 段落
    ○ リスト
    ○ コールアウト(例)
    https://docs.flutter.dev/get-started/test-drive 文脈からは外れるが、ユーザーに伝えておきたいことを、目立つように書いているのがコールアウト

    View Slide

  63. ドキュメントにまつわる真実
    ● ユーザーは情報を探してドキュメントにたどり着く
    ● ユーザーは書いてある内容をほとんど読まない

    View Slide

  64. ユーザーはFパターンでドキュメントを読む
    https://www.nngroup.com/articles/f-shaped-pattern-reading-web-content-discovered/

    View Slide

  65. 何がユーザーにとって大事か?
    ● せっかく書いたから読んで欲しい
    ● ユーザーが必要な情報をすばやく見つけられるのが一番良い
    ○ そのために「流し読み」しやすい構成にする

    View Slide

  66. どうすれば流し読みしやすくなるか?
    ● 最も重要な情報を冒頭で述べる
    ○ たとえば手順書であれば、手順書完了時点で達成できることを書く

    View Slide

  67. https://docs.flutter.dev/development/ui/layout/tutorial
    冒頭で達成できることが書いてある

    View Slide

  68. どうすれば流し読みしやすくなるか?
    ● 最も重要な情報を冒頭で述べる
    ○ たとえば手順書であれば、手順書完了時点で達成できることを書く
    ● 大きな文章のかたまりを分割する
    ○ 長い段落は流し読みが困難
    ○ 見出し・リスト・サンプルコード・図表 で分割する

    View Slide

  69. https://docs.flutter.dev/development/ui/layout/building-adaptive-apps
    段落と図表(実際は動画)で分割している例

    View Slide

  70. どうすれば流し読みしやすくなるか?
    ● 最も重要な情報を冒頭で述べる
    ○ たとえば手順書であれば、手順書完了時点で達成できることを書く
    ● 大きな文章のかたまりを分割する
    ○ 長い段落は流し読みが困難
    ○ 見出し・リスト・サンプルコード・図表 で分割する
    ● 複数の方法が含まれているなら方法ごとに分割する
    ○ 例:GUIを使うパターン、CUIを使うパターン

    View Slide

  71. どうすれば流し読みしやすくなるか?
    ● 最も重要な情報を冒頭で述べる
    ○ たとえば手順書であれば、手順書完了時点で達成できることを書く
    ● 大きな文章のかたまりを分割する
    ○ 長い段落は流し読みが困難
    ○ 見出し・リスト・サンプルコード・図表 で分割する
    (超重要。5章まるまるサンプルコードのみ。詳細は書籍にて)
    ● 複数の方法が含まれているなら方法ごとに分割する
    ○ 例:GUIを使うパターン、CUIを使うパターン

    View Slide

  72. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  73. ドキュメントも仮説検証対象
    ● プロダクトに開発した機能がユーザーに刺さるとは限らない
    ○ 分からないので仮説検証する

    View Slide

  74. ドキュメントも仮説検証対象
    ● プロダクトに開発した機能がユーザーに刺さるとは限らない
    ○ 分からないので仮説検証する
    ● ドキュメントは、プロダクトの機能の一部
    ○ 他機能と同様に「フィードバック(FB)」をベースに検証が必要
    → FBをどうやって集めればいい?

    View Slide

  75. ユーザーFBの集め方
    ● フィードバックを受け取るための経路を用意する
    ● 例
    ○ ドキュメントのページへformなどを埋め込む

    View Slide

  76. ユーザーFBの集め方
    ● フィードバックを受け取るための経路を用意する
    ● 例
    ○ ドキュメントのページへformなどを埋め込む
    ○ サポートチケットから読み取る

    View Slide

  77. ユーザーFBの集め方
    ● フィードバックを受け取るための経路を用意する
    ● 例
    ○ ドキュメントのページへformなどを埋め込む
    ○ サポートチケットから読み取る
    ○ ドキュメントに対する感情を集める
    https://learn.microsoft.com/ja-jp/azure/virtual-machines/linux/quick-create-cli

    View Slide

  78. ユーザーFBの集め方
    ● フィードバックを受け取るための経路を用意する
    ● 例
    ○ ドキュメントのページへformなどを埋め込む
    ○ サポートチケットから読み取る
    ○ ドキュメントに対する感情を集める
    ○ ユーザーサーベイを実施する

    View Slide

  79. ユーザーFBの集め方
    ● フィードバックを受け取るための経路を用意する
    ● 例
    ○ ドキュメントのページへformなどを埋め込む
    ○ サポートチケットから読み取る
    ○ ドキュメントに対する感情を集める
    ○ ユーザーサーベイを実施する
    ○ ユーザーコミュニティ(会)を作り、そこで質問する

    View Slide

  80. ユーザーFBの活用方法
    ● 集め始めると FB が大量※に蓄積される
    ○ Quick Fixできるものから、詳細な検討が必要なものまで色々
    (※ FBに見せかけたサポート依頼や、バグ報告まで最初はなんでも混ざっている)

    View Slide

  81. ユーザーFBの活用方法
    ● 集め始めると FB が大量に蓄積される
    ○ Quick Fixできるものから、詳細な検討が必要なものまで色々
    ● そこで、そもそも有効なFBかどうか、また優先度をトリアージする
    ○ その課題は有効か?
    ○ その課題は修正可能か?(重複してない?再現可能? など)
    ○ どのぐらい重要か?

    View Slide

  82. ユーザーFBの活用方法
    ● 集め始めると FB が大量に蓄積される
    ○ Quick Fixできるものから、詳細な検討が必要なものまで色々
    ● そこで、そもそも有効なFBかどうか、また優先度をトリアージする
    ○ その課題は有効か?
    ○ その課題は修正可能か?(重複してない?再現可能? など)
    ○ どのぐらい重要か?
    → kubernetes の例で見てみましょう!

    View Slide

  83. https://www.kubernetes.dev/docs/guide/issue-triage/
    ←次ページで
     この辺を拡大します

    View Slide

  84. 新規Issueの確認
    Issueを分類
    優先度付け
    https://www.kubernetes.dev/docs/guide/issue-triage/

    View Slide

  85. https://www.kubernetes.dev/docs/guide/issue-triage/

    View Slide

  86. https://www.kubernetes.dev/docs/guide/issue-triage/
    超重要
    あったらいいけどすぐやらない
    なるべく早くやる。できれば次のリリースで。
    長期的には重要
    たぶん有用だけどまだ十分な支持がない

    View Slide

  87. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  88. 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

    View Slide

  89. 優れたドキュメントって何だろう?
    ● ドキュメントの品質の定義
    「ドキュメントが優れているのは目的にかなっている場合である。」

    View Slide

  90. 優れたドキュメントって何だろう?
    ● ドキュメントの品質の定義
    「ドキュメントが優れているのは目的にかなっている場合である。」
    ユーザーの特定の行動を促進すること + 組織のゴールを達成すること

    View Slide

  91. ドキュメントの品質の構成要素
    ● 機能品質
    ○ ドキュメントの目的やゴールが達成されているか?

    View Slide

  92. ドキュメントの品質の構成要素
    ● 機能品質
    ○ ドキュメントの目的やゴールが達成されているか?
    ● 構造品質
    ○ ドキュメント自体がうまく書かれているか?
    ○ うまく構成されているか?

    View Slide

  93. 機能品質
    ● アクセシビリティがあること
    ● 目的があること
    ● 見つけやすいこと
    ● 正確なこと
    ● 完全であること
    構造品質 (3C)
    ● Clear (明確な)
    ● Concise (簡潔な)
    ● Consistent (一貫している)
    それぞれの詳細は書籍参照のこと

    View Slide

  94. ドキュメントの品質の構成要素
    ● 機能品質
    ○ ドキュメントの目的やゴールが達成されているか?
    ● 構造品質
    ○ ドキュメント自体がうまく書かれているか?
    ○ うまく構成されているか?
    さて、どちらの品質が重要でしょう?🤔

    View Slide

  95. ドキュメントの品質の構成要素
    ● 機能品質
    ○ ドキュメントの目的やゴールが達成されているか?
    ● 構造品質
    ○ ドキュメント自体がうまく書かれているか?
    ○ うまく構成されているか?
    さて、どちらの品質が重要でしょう?🤔
    → 機能品質 ∵どれだけ最高の表現でもゴール達成しないと無価値

    View Slide

  96. ドキュメントのメトリクス
    ● Web解析ツールを使えば様々なメトリクスを測定可能
    ○ PV数
    ○ ユニークユーザー数
    ○ 直帰率
    ○ TTHW (Time to Hello World)
    ○ etc…

    View Slide

  97. ドキュメントのメトリクス
    ● Web解析ツールを使えば様々なメトリクスを測定可能
    ○ PV数
    ○ ユニークユーザー数
    ○ 直帰率
    ○ TTHW (Time to Hello World)
    ○ etc…
    ● 使い切れないほどあるため、確認するメトリクスの絞り込みが重要

    View Slide

  98. メトリクス活用のTips (の一部)
    ● メトリクス活用の計画を作る
    ○ なぜ測定したいのか?
    ○ その情報を使って何をするのか?
    ○ その努力で、どのように組織のゴールが前に進められるのか?

    View Slide

  99. メトリクス活用のTips (の一部)
    ● メトリクス活用の計画を作る
    ○ なぜ測定したいのか?
    ○ その情報を使って何をするのか?
    ○ その努力で、どのように組織のゴールが前に進められるのか?
    ● 基準値を確立する
    ○ ベースラインがあれば何らかの変更の前後で比較可能になる
    (=計測して基準値があるから改善できるようになる)

    View Slide

  100. 今日のアジェンダ
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  101. 日本語の作文技術に関する書籍は多く存在
    タイトルが
    「ヘルプサイトの作り方」であるが
    作文技術が多く言及されている

    View Slide

  102. 事実と意見をはっきり区別する
    ● 手順書などのテクニカルドキュメントに意見は紛れこみにくい
    ● 一方で設計の思想が現れるドキュメントは主観が入る
    ○ ここで事実と意見が混ざると理解しやすさ・信憑性が低下する

    View Slide

  103. 事実と意見が曖昧な例
    “近頃の学生は整った文章を書く能力がないという
    声をよく聞くが,私はこれは主に理科系の学生に関
    していわれていることだと思う.
    理科系の学生がきちんとした文章を書けないことに
    ふしぎはない.
    彼らの本領は文学ではないからである.”
    1515/3419

    View Slide

  104. “近頃の学生は整った文章を書く能力がないという
    声をよく聞くが,私はこれは主に理科系の学生に関
    していわれていることだと思う.
    理科系の学生がきちんとした文章を書けないことに
    ふしぎはない.
    彼らの本領は文学ではないからである.”
    1515/3419
    意見
    事実と意見が曖昧な例

    View Slide

  105. “近頃の学生は整った文章を書く能力がないという
    声をよく聞くが,私はこれは主に理科系の学生に関
    していわれていることだと思う.
    理科系の学生がきちんとした文章を書けないことに
    ふしぎはない.
    彼らの本領は文学ではないからである.”
    1515/3419
    意見
    突然、事実になったため
    議論の土台がグラグラに
    事実と意見が曖昧な例

    View Slide

  106. 修飾の順序
    ● 例:以下の紙を「言葉」で表現する
    https://unsplash.com/photos/WX5jK0BT5JQ
    白い
    厚手
    横線がある

    View Slide

  107. 修飾の順序
    ● 節(述語を含む)を先に、句を後に
      白い横線の引かれた厚手の紙 
      厚手の横線の引かれた白い紙 
      横線の引かれた厚手の白い紙
    P.43および70
    わかりやすい文はどれ?

    View Slide

  108. 修飾の順序
    ● 節(述語を含む)を先に、句を後に
    ❌ 白い横線の引かれた厚手の紙 (=横線が白い ことになる)
    ❌ 厚手の横線の引かれた白い紙 (=横線が厚手 に捉えられる)
    ✅ 横線の引かれた厚手の白い紙
    P.43および70
    述語がある

    View Slide

  109. 修飾の順序
    ● 節(述語を含む)を先に、句を後に
    ❌ 白い横線の引かれた厚手の紙 (=横線が白い ことになる)
    ❌ 厚手の横線の引かれた白い紙 (=横線が厚手 に捉えられる)
    ✅ 横線の引かれた厚手の白い紙
    ● その他の原則
    ○ 長い修飾句ほど先に、短いほどあとに
    ○ 大状況から小状況へ、重大なものから重大でないものへ
    ○ 親和度(なじみ)の強弱による配置転換
    P.43および70

    View Slide

  110. 動詞に「方法」「こと」などを付けて安易に名詞化しない
    ● 冗長な、くどい日本語になるため
    P.104

    View Slide

  111. 動詞に「方法」「こと」などを付けて安易に名詞化しない
    ● 冗長な、くどい日本語になるため
    ● 例:
    ❌ 機能Aを使用するという方法もあります
    ✅ 機能Aも使用できます
    P.104

    View Slide

  112. 動詞に「方法」「こと」などを付けて安易に名詞化しない
    ● 冗長な、くどい日本語になるため
    ● 例:
    ❌ 機能Aを使用するという方法もあります
    ✅ 機能Aも使用できます
    ❌ Bにより改善することができます
    ✅ Bにより改善できます
    P.104
    と、いくつかの書籍から説明したように日本語の作文技術も学んでおくのがおすすめです

    View Slide

  113. 112
    ということで

    View Slide

  114. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  115. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  116. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  117. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  118. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  119. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α)

    View Slide

  120. 今日お話ししたこと
    ● 書籍の概要
    ● 特に意識しておきたい箇所
    ○ 読み手の理解(1章)
    ○ ドラフトの執筆(3章)
    ○ フィードバックの収集(8章)
    ○ ドキュメントの品質測定(9章)
    ● 時間があれば日本語特有の観点(+α) → 良書で補完!

    View Slide

  121. 120
    ゴールのおさらい

    View Slide

  122. 今日のゴール (イベント終了時)
    ● ドキュメントライティングのスキルが高まっている
    ○ ドキュメントライティングの概要を知っている
    ○ ドキュメントの「準備」「作成」「運用」で
    重要なポイントを理解している
    ● (書籍でカバーされていないが抑えておくと良い)
    日本語文章で大事な点を知っている

    View Slide

  123. とはいえ、まだまだ話していない内容がたくさんある!
    ● 良いサンプルコードってなんだろう?
    ● 良いビジュアルコンテンツ、図表ってなんだろう?
    ● 作ったとして、どうやってレビューすればいいんだろう?
    ● 良いフィードバックって何だろう?
    ● ドキュメントが増えてきたらどうやって全体構成すればいいんだろう?
    ● ドキュメントの廃止(deprecate) ってどうやればいいんだろう?
    ● etc…

    View Slide

  124. ● 良いサンプルコードってなんだろう?
    ● 良いビジュアルコンテンツ、図表ってなんだろう?
    ● 作ったとして、どうやってレビューすればいいんだろう?
    ● 良いフィードバックって何だろう?
    ● ドキュメントが増えてきたらどうやって全体構成すればいいんだろう?
    ● ドキュメントの廃止(deprecate) ってどうやればいいんだろう?
    ● etc…
    まだまだ話していない内容がたくさんある!
    書籍に全部書いてあります!
    よろしくお願いします!
    (おしまい)

    View Slide