寿命の長いドキュメントの 鮮度を保つ仕組み

D-Plus Osaka #1 開発生産性を高めたい！関西エンジニアのためのTips共有会

Transcript

1. D-Plus Osaka #1 開発生産性を高めたい！関西エンジニアのための Tips共有会 寿命の長いドキュメントの 鮮度を保つ仕組み Bill One Engineering Unit 岡本 拓也
2. 写真が入ります 岡本　拓也 技術本部 Bill One Engineering Unit Core Business UMグループ 2017年からWebエンジニアのキャリアをスタート。 SESでのシステム開発やSaaS企業でのWebアプリ開発の 経験を積んだ後、2023年にSansan株式会社に中途入社。 入社後はBill Oneの開発に従事し、現在は申請・承認機能 の開発チームの Technical Lead を担当しています。
3. 請求書受領から、月次決算を加速する インボイス管理サービス「 Bill One」 あらゆる請求書をオンラインで受け取り、 企業全体の請求書業務を加速する インボイス管理サービスです。
4. 請求書 発行 経費 精算 請求書 受領 月次決算を加速する 3
5. ドキュメント鮮度日付を導入し、 長期間利用されるドキュメントが定期的に更新される仕組みを構築した話 - ドキュメントの寿命と鮮度 - 運用手順書の課題 - 改善の実施 - 効果 - まとめ アジェンダ
6. ドキュメントの寿命と鮮度
7. プロダクト開発や運用で、そのドキュメントが有用であり続ける期間 - 寿命の短いドキュメント - タスクやスプリントが終了した時点など、特定の時点でのドキュメント - ex) 議事録・調査メモ・開発ドキュメント - 寿命の長いドキュメント - プロダクトや組織が生き続ける限り必要なドキュメント - ex) システム構成図・実装方針・運用手順書 - 情報の陳腐化を防ぎ最新情報を保つ必要がある 寿命が長いドキュメントの陳腐化を防ぐために鮮度という指標を追う ドキュメントの寿命
8. - 鮮度 - 閲覧時に、内容が最新状態で品質が保たれていることを示す指標 - 鮮度が高いほど正確に情報伝達が可能になる - 鮮度が低いことのリスク - 古い情報を基にした意思決定が発生したり、誤解や作業ミスが発生する - ドキュメントの信頼性が失われ参照されなくなり、ドキュメント文化が失われていく - 鮮度が求められないドキュメントもある - 特定の時点の最新情報を管理するドキュメント - ex) 議事録・メトリクス調査資料 ドキュメントの鮮度
9. 運用手順書の課題
10. - 機能では実現できないことを、開発者が手作業で実現する際に参考にするド キュメント - ex) データの物理削除・データ不整合の解消など - Bill Oneは運用が当番制で、開発担当チーム以外のチームが運用する場合も あるため、正確で再現性のあるドキュメントである必要がある Bill Oneの運用手順書
11. - 手順書ごとに品質がバラバラ - 対象読者は有識者なのか、開発者全員なのか不明 - ドキュメントの理解に時間がかかる - 背景知識を正しく理解しないと正しい手順を踏めない可能性がある - 長く更新されていない手順書がある - 古いテーブル情報のクエリが残っている - 使って良い手順書なのか判断できず、作成者に聞く必要がある - 運用作業効率の低下、インシデント発生リスクがある - リスクが顕著になると、開発生産性が低下する - 寿命が長いドキュメントの鮮度を保つ仕組みが必要 運用手順書の課題
12. 改善の実施
13. - 各開発チームから有志のメンバー6名が集まる - Bill One開発チームは横串チームを気軽に結成でき、横断的な課題を組織全体で 改善できる - 短期間で改善を行い解散する予定 運用手順書改善チームの発足
14. - 手順書ごとに品質がバラバラ - 求められる品質を定義 - 運用手順書テンプレートを作成 👉 - 長く更新されていない手順書がある - ドキュメントオーナーの導入 - 品質を担保する責務を明確にする - ドキュメント鮮度日付の導入 具体的な改善
15. - 「Googleのソフトウェアエンジニアリング」10章で紹介されている - ドキュメントの鮮度が失われ旧式のドキュメントとなる日付 - 鮮度を3ヶ月に設定し、最終更新日が9月15日の場合 - 鮮度日付は12月15日 - 鮮度日付が切れたドキュメントのオーナーにメールで更新のリマインダーメールを 送信している - 低コストでドキュメントの長期的な保守ができる - 鮮度が低いことの問題 - 古いコードが問題を起こす可能性があるように、 古いドキュメントも問題を起こす可能性がある ドキュメント鮮度日付とは
16. - 3ヶ月を指標に鮮度日付を導入 - 機能開発サイクルが最大3ヶ月で、機能追加や改修があれば運用手順書を書き換 える可能性があるため - makeを導入 [https://www.make.com] - 様々なWebサービスを統合し、タスクを自動化できるWebサービス - Slack, Notion, Miro, Google Workspaceなどと連携可能 - Web UIからローコードで定期的なjobの実行や、webhookを利用したタスクの実 行ができる - 運用手順書を管理しているNotionから3ヶ月更新されていない手順書を取得 し、そのメンテナンスオーナーにSlackで通知する makeを利用したドキュメント鮮度日付の導入
17. makeを利用したドキュメント鮮度日付の導入 ①毎週水曜日 15:00に起動 ②最終更新日から 3ヶ月過ぎている手順書を取得 ④ドキュメントオーナーの Slackメンション取得 ⑤Slack APIの流量制限対策で sleep ⑥Slackでドキュメント更新を促す メッセージを通知 ③ドキュメントオーナーごとに ドキュメントを集約 ⑦スレッドにドキュメントのリンクを投稿
18. - 更新だけではなく、不要なドキュメントの削除も促しています 実際の通知内容
19. 改善の効果
20. - 90%の運用手順書が 3ヶ月以内に更新されている！ - 153件 / 169件 - 鮮度日付導入後のオペレーションミスはヒヤリハットの1件のみ - 1年間で80件の不要な運用手順書削減に成功！ - 手順書の検索性向上 - 無効な手順書での運用作業を防止 - ドキュメントの鮮度を保つことで、正確な運用ができ生産性低下を防止できてい る 改善の効果
21. まとめ
22. - ドキュメント鮮度日付を導入し、寿命が長く鮮度が必要なドキュメント管理体制 を構築 - 3ヶ月という指標を置いて管理 - 対象のドキュメントのライフサイクルから指標を決めること - ぜひ定期的にメンテナンスが必要なドキュメントの管理の参考にしてみてくださ い まとめ
23. Sansan 技術本部 募集ポジション紹介 https://media.sansan-engineering.com/