何のためにドキュメントを書くのか

Transcript

1. 何のためにドキュメントを書くのか tsuji-108 @ 株式会社Gaji-Labo 2024/05/15 第15回 LTラジオ
2. 自己紹介 株式会社Gaji-Labo フロントエンドエンジニア 最近はRemixにお熱です。 ＠tsuji-108
3. 私「ドキュメントの書き⽅、何も分からん🤪」 私「テクニックは置いておいて、何のためにドキュメントを書くか整理する か。」 ↓ 「ドキュメントの⽬的 = 知識の積集合を形成する」と捉え直した。 ↓ 知識の積集合を形成するためには… 1. 書き⼿と読み⼿の知識量を同量にする 2. 書き⼿と読み⼿の認識を共通化する 何のためにドキュメントを書くのか
4. まずドキュメントの読み⼿を想像する • 読み⼿は誰か？ ◦ システムに精通している⼈？ / はじめて触る⼈？ ◦ 得意分野は？ / 苦⼿分野は？ • 読み⼿の⽬的は何か？（ドキュメント読破が⽬的ではないはず。） ◦ 読み⼿はシステムを使いたい？ / システムの機能改修をしたい？ • 書き⼿の知識量を100とすると、読み⼿の知識量をはいくらか？ ↓ 読み⼿を想像すると、ドキュメントに書く事‧書かなくとも良い事が⾒えてく る。 1. 書き⼿と読み⼿の知識量を同量にする 1. 書き⼿と読み⼿の知識量を同量にする
5. • 読み⼿：同僚のエンジニア。 ◦ ⽬的：ある機能Xの改修のため、その周辺技術のみ把握したい。 ◦ 知識量：60 →システムの概要はシンプルなドキュメントで事⾜りるかもしれない。機能Xにつ いては、詳細に書いた⽅が良さそう。 • 読み⼿：はじめてシステムに触るパートナーエンジニア。 ◦ ⽬的：システムの全容を把握したい。 ◦ 知識量：0 →はじめからから丁寧に解説したドキュメントがあった⽅が良さそう。 読み⼿の想定例 1. 書き⼿と読み⼿の知識量を同量にする
6. 1. 書き⼿と読み⼿の知識量を同量にするをベン図で表すと… 読み⼿ の 知識量 書き⼿ の 知識量 ▼想定 • 読み⼿：同僚のエンジニア • ⽬的：ある機能Xの改修のため、その周辺技術を把 握したい • 知識量：約60/100 1. 書き⼿と読み⼿の知識量を同量にする
7. 1. 書き⼿と読み⼿の知識量を同量にするをベン図で表すと… ドキュメントを読むことで、読み⼿の知識量が書き⼿の知識量に近づいていく。 読み⼿ の 知識量 書き⼿ の 知識量 1. 書き⼿と読み⼿の知識量を同量にする
8. 1. 書き⼿と読み⼿の知識量を同量にするをベン図で表すと… ドキュメント読了後に書き⼿と読み⼿の知識量が同量になる 読み⼿ の 知識量 書き⼿ の 知識量 1. 書き⼿と読み⼿の知識量を同量にする
9. ⼈間同⼠の認識を合わせる事はとても難しい。 読み⼿がドキュメントを読んだだけでは、認識の相違がどうしても発⽣してしま う。 ↓ 書き⼿が読み⼿を巻き込み、ドキュメントのレビュー会や読み合わせ会を実施し て、認識を共通化するフェーズが必要になる。 （「⽤語集」や「よくあるQ&A」などをドキュメントに追記するとなお良し！） 2. 書き⼿と読み⼿の認識を共通化する 2. 書き⼿と読み⼿の認識を共通化する
10. 2. 書き⼿と読み⼿の認識を共通化するをベン図で表すと… 1. 書き⼿と読み⼿の知識量を同量にするを終えた状態から… 読み⼿ の 知識量 書き⼿ の 知識量 2. 書き⼿と読み⼿の認識を共通化する
11. 2. 書き⼿と読み⼿の認識を共通化するをベン図で表すと… 読み⼿ の 知識量 書き⼿ の 知識量 レビュー会や読み合わせ会を経て、書き⼿と読み⼿の認識を合わせていく。 2. 書き⼿と読み⼿の認識を共通化する
12. 2. 書き⼿と読み⼿の認識を共通化するをベン図で表すと… 書き⼿と読み⼿ の 知識量 最終的に、書き⼿と読み⼿の認識が共通化される = 知識の積集合を形成する。 2. 書き⼿と読み⼿の認識を共通化する
13. 上記は点P(Px, Py)を点Q(Qx, Qy)を中⼼に反時計回りにθ度回転させる数式です。 上記の数式を実現する関数Rとして実装し、下記の解説⽂をドキュメントに書きま した。 ▼解説⽂（※回転する向きに触れていない点に留意） 関数Rは⼆次元座標上の任意の点Pを、別の任意の点Qを中⼼にθ度回転させる関数です。 P、Q、θの3つの引数を受け取り、戻り値として{ x: 数値, y: 数値 }を返却します。 引数P、Qは座標であり、形式は{ x: 数値, y: 数値 }です。引数θは度(°)を受け取ります。 共通認識の例（悪例ですが、あしからず。） 2. 書き⼿と読み⼿の認識を共通化する
14. 共通認識の例 ドキュメントの解説⽂を読んだAさんとBさんは、こう思いました。 • A「関数Rは、引数Pを引数Qを中⼼に反時計回りにθ度回転させる関数だ。」 • B「関数Rは、引数Pを引数Qを中⼼に時計回りにθ度回転させる関数だ。」 →「反時計回り」と「時計回り」で認識の相違が発⽣した！ 2. 書き⼿と読み⼿の認識を共通化する Q P こっち？ こっち？ θ° θ°
15. ドキュメントにどこまで詳細を記述するべきか 2. 書き⼿と読み⼿の認識を共通化する • A「回転⽅向の⾔及がなくとも、反時計回りの回転⾏列と察しがつくよ。」 • B「回転⽅向が書かれていないから、反時計回り‧時計回りのどちらにも解釈 できてしまうよ。回転⽅向を明記した⽅が分かりやすいし、親切だよ。」 解説⽂に「反時計回りに回転する」と記述するべきか？ ⾔い換えると「Q.ドキュメントにどこまで詳細を記述するべきか？」 A.書き⼿と読み⼿で認識を共通化できていない = 知識の積集合の補集合に位置する要素なら、ドキュメントに明記すべき
16. ドキュメントにどこまで詳細を記述するべきか 2. 書き⼿と読み⼿の認識を共通化する 書き⼿と読み⼿ の 知識量 書き⼿は知っているが、読み⼿が 知らない知識 「反時計回りに回転する」は書き ⼿は知っているが、Bさんは知ら ない。 => ドキュメントに明記すべき 書き⼿も読み⼿も知っている知識 「反時計回りに回転する」は書き⼿も Aさんも知っている。 => 詳細の解説は冗⻑になるかも。
17. 「ドキュメントの⽬的 = 知識の積集合を作る」と捉えて 1. 書き⼿と読み⼿の知識量を同量にする 2. 書き⼿と読み⼿の認識を共通化する を意識していけば、良いドキュメントが書けそう！ まとめ
18. 会社紹介 プロダクトの課題を⼀緒に解決します。 最適な技術と、適切な⼿段で。 Gaji-Laboは、スタートアップのプロダクト開発 や新規事業チームの成⻑⽀援の会社です。 フロントエンド開発やUIデザインなどの専⾨技 術の提供を軸に、成⻑⽀援のためのチームワー クの提供を⼀番⼤切にしています。 フロントエンド開発 UIデザイン / 情報設計 チーム / プロセス⽀援