ドキュメントとの付き合い方を考える

2024/10/3 【ペチオブ LT 会】オフラインでわいわい LT & 交流会『ドキュメントとの付き合い方を考える
』

これまで考えてこなかった「ドキュメントとの付き合い方」について、システムのリプレースに際し考え直したお話しです。

Transcript

1. ドキュメントとの 付き合い方を考える レバテック開発部 内藤 翔太
2. |　© 2024 Levtech Co., Ltd. 2 レバテック開発部 ITSプロダクト開発グループ / 契約請求ドメインチーム 内藤 翔太 SHOTA NAITO ・2023年04月　レバレジーズ株式会社に新卒入社 ・2023年11月　レバテック開発部に異動 ・直近は、システムのリプレースに取り組んでいます！
3. |　© 2024 Levtech Co., Ltd. 3 • はじめに • これまでの経験 • ドキュメントって本当に必要？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
4. |　© 2024 Levtech Co., Ltd. 4 • はじめに • これまでの経験 • ドキュメントって本当に必要？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
5. |　© 2024 Levtech Co., Ltd. 5 今日伝えたいこと 組織のパフォーマンスを上げるためには ドキュメントとその品質が欠かせない
6. |　© 2024 Levtech Co., Ltd. 6 突然ですが...
7. |　© 2024 Levtech Co., Ltd. 7 皆さんはドキュメント書いてますか？
8. |　© 2024 Levtech Co., Ltd. 8 僕は書いてます
9. |　© 2024 Levtech Co., Ltd. 9 僕は書いてます というより書くようになりました！
10. |　© 2024 Levtech Co., Ltd. 10 僕は書いてます というより 書くようになりました 書くようになった背景を説明するために、少しこれまでの経験を...
11. |　© 2024 Levtech Co., Ltd. 11 • はじめに • これまでの経験 • どんなドキュメントを書いてる？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
12. |　© 2024 Levtech Co., Ltd. 12 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09
13. |　© 2024 Levtech Co., Ltd. 13 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09
14. |　© 2024 Levtech Co., Ltd. 14 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 0→1での経験が多かった どんどん開発を進めてアウトカムを出していこう！ ドキュメントのモチベーションは低め...
15. |　© 2024 Levtech Co., Ltd. 15 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09
16. |　© 2024 Levtech Co., Ltd. 16 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 システム構成がどうなってるのかパッと分からない... なぜこの設計にしてるの...？ 問い合わせが来たけど、仕様書がないからコード読むしかない...
17. |　© 2024 Levtech Co., Ltd. 17 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09
18. |　© 2024 Levtech Co., Ltd. 18 2022/04- 2023/03 新卒研修　研修 + 0→1での経験 2023/04 - 2023/11 システムの運用 + 施策 2023/12 - 2024/03 これまでの経験 インターン　0→1での経験がメイン システムのリプレース 2024/04 - 2024/09 運用負荷を軽減するためのドキュメント は絶対残そう！！ ex) システム構成図, ADR, 機能仕様書, etc.
19. |　© 2024 Levtech Co., Ltd. 19 僕は書いてます というより 書くようになりました と思いつつも、ドキュメントは本当に必要なのかを問い直してみる
20. |　© 2024 Levtech Co., Ltd. 20 • はじめに • これまでの経験 • ドキュメントって本当に必要？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
21. |　© 2024 Levtech Co., Ltd. 21 DORA（DevOps Research and Assessment）に学ぶ ドキュメントって本当に必要？ https://dora.dev/capabilities/documentation-quality/
22. |　© 2024 Levtech Co., Ltd. 22 DORA（DevOps Research and Assessment）に学ぶ ドキュメントって本当に必要？ やはりドキュメントは必要で、特にその品質が重要 https://dora.dev/capabilities/documentation-quality/
23. |　© 2024 Levtech Co., Ltd. 23 • はじめに • これまでの経験 • ドキュメントって本当に必要？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
24. |　© 2024 Levtech Co., Ltd. 24 ドキュメントの品質を上げるためには？ 自チームでは、Diátaxis × Github で管理している Github Diátaxis 他にも ・Google Document（SpreadSheet） ・Datadog のドキュメントが存在するが、 リプレースの文脈で作成した開発関連の ドキュメントは Github から追えるように = 検索の I/F は Github に集約したい！ + 検索機能の検索性も特に問題なし ・Tutorials ・How-to Guides ・Explanation ・Reference の 4 象限でドキュメントを管理するこ とで、目的に応じた情報を簡単に 見つけられるように！ + ドキュメント作成場所も明確に 検索性を高める
25. |　© 2024 Levtech Co., Ltd. 25 目的や達成できることを冒頭に記載する ドキュメントの品質を上げるためには？ 参考: エンジニアのためのドキュメントライティング ユーザは F パターンでドキュメントを読む → 冒頭の数行にユーザが欲しい情報を持ってくる
26. |　© 2024 Levtech Co., Ltd. 26 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？
27. |　© 2024 Levtech Co., Ltd. 27 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。
28. |　© 2024 Levtech Co., Ltd. 28 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。 △ 漠然としていて、具体的な影響や問題点が分からない....
29. |　© 2024 Levtech Co., Ltd. 29 ビックワードを避ける ドキュメントの品質を上げるためには？ Q. 新システムで現行システムのセッションストアからセッション情報を読み込むと？ A. 新システムのセッション管理が独立せず、システムの複雑性が増加する。 △ A. 新システムのセッション管理が独立せず、新システムでの実装時に 現行システムのセッション管理を考慮する必要が生じる。 その結果、システム構成が複雑になることによる障害発生リスクの増加や、 開発工数の肥大化が予想される。 ⭕ 具体的な影響や問題点が分かりやすい！ ・自身が可能なところまで具体に落とす ・自身以外の数名に読んでもらった時に違和感がない
30. |　© 2024 Levtech Co., Ltd. 30 • はじめに • これまでの経験 • ドキュメントって本当に必要？ • ドキュメントの品質を上げるためには？ • まとめ アジェンダ
31. |　© 2024 Levtech Co., Ltd. 31 まとめ • 0→1での開発ではドキュメントが必要になることがあまりないため、 ドキュメントへの意識が薄くなりがち • 運用を経験するとドキュメントの存在価値を身をもって知ることができる • DORA の分析によれば、ドキュメントの品質と組織のパフォーマンスの間には 明確な関連性がある • ドキュメントの品質を向上するためには、「検索性を上げる」「目的や達成できる ことを冒頭に記載する」「ビックワードを避ける」ことが重要
32. |　© 2024 Levtech Co., Ltd. 32 今日伝えたいこと 組織のパフォーマンスを上げるためには ドキュメントとその品質が欠かせない 再掲