こんにちは、Records事業部エンジニアの佐藤(@r_sato1201)です。
今回は、Records事業部開発チーム発足時から取り組んできたドキュメントの管理・運用に関して書きたいと思います。
ドキュメント化する必要性
そもそも、なぜドキュメント化する必要があるのかについて書きたいと思います。
私が考えるドキュメント化の目的は、チームの暗黙知を形式知にすることです。
私達はスクラムで開発していますが、スクラムチームが日々プロダクトを作りながら得た経験や知識を新規メンバーに伝えることは容易ではありません。
スクラムチームでの所属歴の長さの違いによってコミュニケーションロスが発生しないように、ナレッジをドキュメント化し誰でも参照できるようにする必要があると考えています。
ドキュメントを管理・運用する上で想定していないこと
とはいえ、全てのナレッジをドキュメント化できるとは考えていません。
ドキュメントの管理・運用ルールを定めてチームに展開する上で誤解が生じる可能性があったので、まずはじめに以下のドキュメントを管理・運用する上で想定していないことを伝えました。
- ドキュメントを読めばスクラムチームのナレッジが全て頭に入る
- 分からないことがあったら、コミュニケーションを取らずドキュメントを読めばいい
- いついかなる時もドキュメントが正である
- 全ての情報をドキュメント化する必要がある
ドキュメント管理の課題
ドキュメント管理に対して、今まで私は大別して3つの課題を感じてきました。
1. 作成されない
ドキュメント化したいトピックはあるが、ドキュメント化自体の優先度が低く作成されない。
2. 更新されない
多くのドキュメントは更新するフックがないため、更新がされない。
ドキュメントを更新するタスクを作っても、優先度が低く先送りになってしまう。
古くから存在しているドキュメントの情報が正しいか判別できず、内容の更新をしていいか判断できない。
3. 整理しておらず参照しにくい
ドキュメントのインデックスがなく、ドキュメントを見つけることができない。
似たようなドキュメントが乱立し、どれを参照すればいいか分からない。
この3つの課題を解決するために、色々なものを参考にドキュメント管理運用を考え実施したので紹介します。
作成フロー
まずは作成フローです。
以下の1から3のステップを繰り返すことで、作成したいドキュメントを漏れなく作成していきます。
1. 今後作成予定のドキュメント一覧に追記する。
今後作成予定のドキュメント一覧表を作成しておき、ドキュメント化したいもの、したほうが良いものを思いついたら随時表に追加していきます。
追加するタイミングでは、ドキュメント化する必要性などは悩まずに、個々人が作成したいと思ったらカジュアルに追記していきます。
2. リファインメントで今後作成予定のドキュメント一覧を確認する
私達は1週間スプリントで開発しています。
スプリントの最終日である金曜日に、今後作成予定のドキュメント一覧を確認します。
ここで、新規に追加されたものをスクラムチームで確認します。
3. 次スプリントで実行する何をドキュメント化するか決定する
今後作成予定のドキュメント一覧にあるものを確認したら、優先度などを考慮し次スプリントでドキュメント化するものを決め、次スプリントで作成します。
このフローを実行することで毎週ドキュメント化することができるため、ドキュメント化の優先度の問題で先送りにされる課題を解決しています。
また、作成したいドキュメントをカジュアルに表に追加するステップを踏んでいるおかげで、ドキュメント化することへのハードルも下がっています。
更新フロー
次は更新フローです。
更新フローはHTTPキャッシュに学ぶ、無理のないドキュメント更新運用を大幅に参考にさせて頂きました。
記事内で紹介されているフローを基にさせて頂きつつ、自動化できる箇所は自動化しました。
フロー内で使われる言葉の定義
フロー自体の説明に入る前に、フロー内で使われる言葉の定義について紹介します。
living-doc
- 更新監視対象のドキュメント
- チームの資産となっているドキュメントのこと
stale, fresh
- living-docの状態を表しています
- stale = 陳腐化 (更新されておらず、情報が古い可能性がある状態)
- fresh = 新鮮 (正しく更新されている状態)
フロー概略
1. 更新監視対象の記事(living-doc)にタグをつける
弊社では、社内の情報管理にesaを利用しています。esaにはタグという機能があり、ドキュメントにタグをつけ分類する機能があるためそれを利用しています。
まずは、更新監視対象にしたい記事にタグをつけます。
- living-doc-30 (更新確認期間が30日間)
- living-doc-45 (更新確認期間が45日間)
- living-doc-90 (更新確認期間が90日間)
タグについてる数字で更新確認をするまでの期間を設定しています。
2. living-doc管理シートにliving-docの一覧を吐き出す
毎週金曜日9時に、タグがついているドキュメントの一覧をliving-doc管理シートに吐き出します。
esaはapiを提供しているため、GASでesaのapiを叩きliving-doc管理シートを更新しています。
このステップではタグがついているドキュメントの一覧を取得し、各living-docの最終更新日と更新期間からドキュメントの更新期限を算出し、各living-docがstaleか否かを判定しています。
3. staleなliving-docをslackに通知
staleなliving-docを全てGASでslackに通知します。
living-doc管理シートの更新フラグを見て判別しています。
4. staleなliving-docを更新する
通知されたstaleなliving-docを一つ一つ確認し、更新していきます。
ドキュメントに価値があり、更新する場合
staleなliving-docにまだ価値がある場合は、情報が古いかを確認し更新します。
ドキュメントに価値がなく、更新しない場合
チームとして価値がないと判断されたliving-docはタグを外します。タグを外すと更新監視対象では無くなるので、このフローからは外れます。
ドキュメントを残す必要がなければ、削除します。
このように、更新するフックを明確につくることで更新に対する課題を解決しています。
ドキュメントインデックス作成フロー
最後に、ドキュメントのインデックスを作成するフローを紹介します。
せっかく価値あるドキュメントが作成されていても、参照しづらいと意味がないためインデックスを作成しています。
こちらもGASで毎日自動的にインデックスを更新しています。
階層毎に見出しをつけて表示することで参照しやすくしています。
運用してみて感想
いまのところうまく回っていると感じています。
うまく回った要因として、２つのポイントが重要だと感じました。
- 明確にドキュメントを更新・作成するフックを設定すること
多くのエンジニア(私も含め)は、実際に動くプロダクトが重要でありドキュメントを作成することが一番重要だとは考えていないはずです。
そのため、ドキュメントに関するタスクは優先度が低くなってしまうことが多いと思います。
しかし、ドキュメント化しいつでもナレッジを引き出せる状態にしておくことの重要性もまた感じていると思います。
優先度が低くなってしまいがちなことは、明確にフックを設定することが必要です。
- 運用する上で辛くならないようできるだけ自動化すること
運用するうえで辛さをなくすことは非常に重要です。
今回設定した運用フローを全て人力で行っていたら、とても続かなかったと思います。
運用が辛く頑張ることで、運用することが目的にならないよう自動化して楽にしましょう。
最後に
現在株式会社ROXXは一緒にはたらく仲間を募集中です。
時代の転換点を一緒につくりましょう！
herp.careers
