ナレッジベースプロジェクトの振り返り

概要

サービスが10年を超えたことで、以下のような問題が発生し、生産性への足かせとなっていました。

1. 様々な機能追加が行われた結果、システムの全体像を把握するのが難しくなり、属人化や認知コストが増加
2. 過去のドキュメントはフォーマットや粒度、場所が統一されておらず見つけづらい
3. 「なぜこの機能を作ったのか」の経緯が失われていることが多く、「元々の実装経緯が分からず、処理を変えられない」、「この機能を消したいけど、誰がどんな目的で使っているのか分からないから提案できない」といった状況が発生

そこで、ドキュメント管理の方針決定と運用を推進する3人ほどのチームを作り、「ナレッジベースプロジェクト」と名付け、整備を進めました。

ドキュメントを作り上げた！ではなく、チーム全員で継続的にドキュメントを残し、資産にするための「仕組み作り」に関する振り返り記事です。

What

ナレッジベース = サービスに関わるエンジニアが早期にパフォーマンスを発揮できるように、厳選した業務知識をまとめたGitHubリポジトリ。知識領域ごとに機能ベースでまとめたドキュメント。

Why

このシステム覚えること多すぎるよね?

1. 全体像や、どこにどんな機能が、なぜあるのか、どうやって動いているのかを把握するのに時間がかかる
2. 覚えるべき領域、優先度もよくわからない
3. 毎度、実装調査や人に聞いたりする必要がある
4. 障害・問い合わせ対応の心理的負担が大きい

開発者がパフォーマンスを発揮するまで時間がかかる

1. 部分的な深い知識だけでは、障害‧問い合わせ対応で活躍
   できない、提案もしづらい
2. 歴の⻑い人にどんどん属人化してしまう
3. 覚える量に圧倒され、諦める、やる気を失う、悲しくなる
   • 俺たちのプロダクトだぜ!という気持ちを持ちづらい
   • どことなく不安になる

コンセプト

1. このサービスにどのような機能が存在し、なぜ存在し、どのように連携しているのか、なるべくスピーディに理解しよう
2. 情報を厳選しよう
   • 「正確な情報」
   • 「メンテナンスされるべき情報」
   • 「最低限は知っておいて欲しい情報」
3. 「T型」知識をつけよう
   • 最低限知るべき知識 (横軸で広く浅く)
     • 今回はこちらを対象に、サービスにJOINしたらまず知ってもらう情報を整備
   • 専門的な深い知識 ( 縦軸で狭く深く )
     • ゆっくりと専門領域を深めてもらう、細かい仕様は各リポジトリで管理
4. 完了の定義を設け、品質を担保しよう
   • GitHubを利用し、ApproveとMergeという過程を経て完了とする
   • オマケの効果として、人事評価や目標設定にも活用しやすい定量的な基準になることも期待

やってみて良かったこと

1. 想定読者を決める
   • その機能の開発に携わったことがない、または初めて知る人向け
2. 「分かっている前提」のCurse of knowledge（知識の呪縛）に陥らないようにする
   • 読んだ人がどうなることを望んでいるのかを考えながら書く
3. ディレクトリを分ける
   • 「/<サービス名>の知識」
     • 今回のコンセプトを表現し、遵守するディレクトリ
   • 「/<サービス名>の開発・運用」
     • 理解するにはもう少し詳細な仕様・フロー図が必要だよね!
     • 実装寄りの情報は壊れやすいため、メンテナンス不可能になる可能性もある
     • 最悪の場合、切り離して捨てる可能性を秘めたディレクトリ
   • その機能の開発に携わったことが無い、または初めて知る人へ
4. GitHubを使ったこと
   • レビューして貰えるので、変更も気軽
   • レビューにより品質担保、情報共有がしやすい
   • 個人目標に設定しやすい
     • レビュー通過の品質かつ、マージまでで完了を評価しやすい
       • ドキュメントをマージした = 知識がついた
   • GitHub Actions で色々出来そう
     • textlintが便利
     • リンク切れ等の検知も楽
5. 管理チームを立てたこと
   • 明確な方針を持ち、ルールや運用の設計をしたこと
     • Google Technical writingをベースに設計、指導
   • 最初に「書いて欲しいこと」の骨組みを作ったこと
     • タイトル、段落を事前に7割程度作成していた
       • 内容のレベル感など期待値を伝えるとともに、書く人が無駄に迷わないようにする
   • 「書いてはいけないもの」は拒否したこと
     • コンセプトに沿わないものは
   • 一人では難しい取り組みだったが、小さな一歩を踏み出すことが出来た

今後に向けての課題

• ドキュメント作成は労力がかかる
  • プロジェクトの見積もりにドキュメント作成も含めるなどの工夫が必要
  • 皆に書いてもらう、習慣にしてもらう、というのが結局最も難しい
• 管理もそれなりに労力がかかる
  • 定期的に構成や導線の見直しが必要

今回は、ドキュメントを作り上げた！ではなく、ドキュメントを継続的に全員で作っていく、という仕組みや取り組みについて書いてみました。