どのようなドキュメントを残すべきか
あくまで個人の意見です
はじめに
昨今、多くの企業はナレッジベースを保持しており、ドキュメントを検索して読んだり、ドキュメントを執筆してナレッジベースに格納したり、といった所作は日常的に行われているかと思います。
このようなナレッジベースを維持運用するにあたり主に課題になるのは以下の 2 点です。
検索でドキュメントを見つけることができない
検索して見つかったドキュメントの内容が最新化されていない
1 は「ドキュメントが存在しない」と「ドキュメントは存在するが検索で上位に出現しない」に分解できますが「ドキュメントは存在するが検索で上位に出現しない」はナレッジベースツールの機能である程度解消できるため、そこまで深刻ではない印象です。そのため今回は検討の対象外とします。
ドキュメントが存在しない
（検索でドキュメントを見つけることができない）検索して見つかったドキュメントの内容が最新化されていない
ドキュメントをたくさん執筆するほど全ての記事の内容を最新に保つことは難しくなるため、この 2 つはある程度トレードオフの関係にあります。
トレードオフに向き合う
ドキュメントはあった方が良く、最新化されていてほしいです。
現実的には難しいので、それぞれのトレードオフの極端な例を見て、良いバランスを取れないか考えていきます。
最新化しなくても良いドキュメント
ドキュメントは必ずしも最新化しなければならないとは限りません。
請求書や契約書をはじめとして、ある時点での事実情報をドキュメントとして保存するようなケースでは、契約や請求の単位でドキュメントを作り、最新化は必要ありません。
日報や議事録もこれに該当します。ある時点での思考や決定事項が記載されているドキュメントであり、更新の必要はありません。日報であれば 1 日単位、議事録であれば開催される単位でドキュメントを作ります。
また、ブレインストーミング時のメモや最新技術のサーベイも部分的に該当します。こういったタスクは実施した日付さえわかれば最新化されている必要はありません。
ある時点の情報である、という日付情報さえあれば最新の情報でなくても問題のないドキュメントは多いです。
これらのドキュメントはメンテナンスコストがほぼかからないため原則作成し、ナレッジベースに登録すべきだと思います。
最新化されていた方が良いドキュメント
最新化されていた方が良いドキュメントも当然あります。
作業手順書、リリース手順書をはじめとする手順書系のドキュメント、オンボーディング資料や研修資料をはじめとする、情報をキャッチアップするためのドキュメントなどです。
これらの資料は作成された日付が書いてあれば良いわけではなく、最新の状態を反映していなければ効果が薄くなります。薄くなるだけなら良いですが、誤った内容が記載されていることにより悪い影響を与えることもあり得ます。
あまり多くはないですが、誤りを含むくらいならナレッジベースに残さない方が良い場合もあります。（あるいは、日付と最新化されていないと意味が薄いことを明記した上でナレッジベースに残す選択もあります。）
例えば環境構築手順書のようなものは、一定時間が経つと誤りを含むことが多くなるため、手順書を読むように依頼するのではなく、熟練したエンジニアとペアプログラミングする等の手段を活用した方が正確で安全かつ早い場合があります。そもそも手順書が不要になるよう自動化しておくことも有効です。
ナレッジベースに残す場合は明確にオーナーを決めて定期的に内容を最新化する必要があります。
なお必ずしもオーナー自身が最新化する必要はなく、閲覧者に誤りがあれば最新化してもらう手段も有効です。
なくても良いドキュメント
以下のケースに当てはまるものは、なくても良いと言えそうです。
ドキュメント化が難しい
ドキュメント化以外の手段で解決できる
皆さんの日常業務は全てドキュメント化されているでしょうか。ドキュメント化されていたら新しく配属されたメンバにとっては有益かもしれないですが、多分されていないと思います。定型化できず、変更が多いからです。
コールセンターの応対マニュアルはドキュメント化されているでしょうか。多分されていると思います。定型化された業務であり変更が少ないからです。
ドキュメント化する対象が頻繁に変更されるモノである場合は、ドキュメントの内容も頻繁に変更しなければならなくなり、メンテナンスのコストが高くなります。常に変更が多いモノであればそもそもドキュメント化することが難しいですし、すぐに陳腐化してしまうのでドキュメント化しない方が良いです。
一時的に変更が多いモノであれば、ある程度落ち着き内容が固まった段階でドキュメント化するのが良いと思います。
人に聞く
決裁権持ってる人は誰だっけ、リリースの承認者は誰だっけ、鍵の暗証番号知ってるのは誰だっけ、のような、それなりに多くの人が知る必要があるものの、変更の多い情報はあまりドキュメント化されていないのではないでしょうか。また、ソースコード内にある細かい処理の説明はドキュメント化されていないと思います。
こういった小規模かつ頻繁に変わるモノはドキュメント化の効果も薄いので人に聞く、といった解決策が利用されることが多いです。
特定の人に負担が偏るリスクや、あまりにも頻度が多いと問題になり得るので極力避けた方が良いと思われがちではありますが、昨今はチャットによるコミュニケーションも一般的になり、人に聞くコストは相対的に下がっています。
あえて人に聞く運用にすることも検討すべきかと思います。
外部のリソースを利用する
全てのドキュメントを自分たちで作成し、メンテナンスする必要はありません。公開されている有用なリソースは活用した方が良いです。
あった方が良いドキュメント
メンテナンスのコストよりも得られる効果が上回る場合はドキュメント化した方が良いと思います。
基本的にはドキュメントの効果は「見る人 x 省略できる工数」です。
多くの人が閲覧するほど、省略できる工数が多いほど効果が大きいです。
ここで大事なのは、工数はスケールしないですが人はスケールすると言う点です。つまり、省略できる工数には限りがありますが、見る人の数にはほとんど限りがないです。
見る人が多ければ基本的には作成した方が良いと考えて良さそうです。
まとめ
最新化しなくても良いドキュメントは原則ナレッジベースに残した方が良いと思います。残すことのデメリットがほとんどないためです。
最新化が必要なドキュメントは、最新化のコスト、誤りを含むことによる悪影響を加味して、ナレッジベースに残さない選択も検討した方が良いと思います。ナレッジベースに残す場合はオーナーを決めて最新の状態を担保すると良いと思います。
なくても良いドキュメントもあります。人に聞く、外部のリソースを頼るなど、情報を持つ代替手段がないか検討しても良いと思います。
見ることによって削減できる工数が多いドキュメント、見る人が多いドキュメントは、存在することによる効果が大きいためあった方が良いと思います。
終わりに
ドキュメントの属性に着目してどのようなドキュメントをナレッジベースに残すべきかを検討してみました。
これはドキュメンテーションしなくても良いかも、とかこれはオーナー決めてきちんと最新化した上で残した方が良さそう、といった議論や意思決定の助けになればとても幸いです。
つらつらとここまで書いて、じゃあこの記事は何に該当するんだろうかと考えると、最新化しなくても良いドキュメントで、あった方が良いドキュメントなのかなと思いましたが、ナレッジベースに登録した方が良いのかはかなり微妙な気がしてしまいました。
この記事が気に入ったらサポートをしてみませんか？