ドキュメントを大量生産してしまう原因を考えてみた
こんにちは、うめぼしです。
ナビタイムジャパンで法人向けサービスの開発・運用を担当しています。
2019年に新卒で入社したのち、「NAVITIME API」、「NAVITIME Tools」の担当を経て、現在は「ビジネスナビタイム動態管理ソリューション」の開発に携わっています。
ドキュメント量産問題
突然ですが、皆さんはドキュメントを作ってますか？
ドキュメントとは、書類、資料、記録（物）、記録する、文書化する、立証する、などの意味を持つ英単語。ITの分野では文字や図表、写真などを組み合わせて作成された文書や、文書としての形式や体裁を持つデータやファイルなどのことをドキュメントという。
一言でドキュメントと言っても、仕様書やマニュアル、構成図といったシステムの仕様に関するものもあれば、議事録や開発に関する手順書、お問合せ時の調査記録、個人的に技術や仕様について勉強した時のメモまで、例を挙げればキリがないです。
自分用だったりプロジェクト用だったり対象はさまざまですが、私はよくドキュメントを作成します。法人向けサービスを担当している関係で、議事録等を作成する機会もよくあります。
また、調査等で他の方が作成したドキュメントのお世話になることも多いです。特に今のプロジェクトに配属されたとき、仕様やサービスの構成、実装時の検討資料や議事録等々ドキュメントが豊富でとても助かったことは記憶に新しいです。
一方、先日私が1〜2年目の頃に携わったAPIの仕様について調べる機会があり、私が作ったドキュメントを見返したのですが、ドキュメントがいっぱいあって欲しい情報がどこにあるのかわからないということがありました。（しかも最終的に欲しい情報はどこにも書いてませんでした..）
ドキュメントがいっぱいある、というのは必ずしも悪いことではありません。先述の通り、私が今のプロジェクトに配属されたときはそれにとても助けられました。
しかし、必要ないドキュメントが大量にあっても探す手間が増えるだけでメリットはないので、できれば回避したい事象です。
今回の記事では調査や検討の過程・学習した内容をまとめた記録としてのドキュメントについて、大量に作成してしまう原因とそれを回避するためのポイントを考えてみたいと思います。
原因
いい機会なので、昔私が作成したドキュメントを見直してみました。
すると、大きく2つの「ドキュメントが増えてしまっている原因」が見えてきました。
ドキュメントの運用ができていない
1つ目はドキュメントの運用ができていないことです。
例えば、今回調べたAPIの情報がまとめてあるフォルダ内の各ドキュメント名称は以下のようになっていました。
ルート検索API
【2/2】ルート検索API
ルート検索APIの仕様改訂
ルート検索APIの仕様まとめ
何もわからない…
全て機能の仕様検討時に作成したドキュメント（Googleスライド）ですが、名称からはどのような内容なのかが全くわからず、結局全てのドキュメントを開いてみる必要がありました。
そのほかにも書いている途中で放置されているドキュメントや情報の更新が止まっているドキュメントがあったり、プロジェクトに関わるドキュメントとメモ等個人用のドキュメントが混在していたりと混沌な状態になっていました。
これでは欲しい情報を見つけられないのは当たり前ですし、きちんと運用できていない可能性からそのドキュメントに書いてあることの信頼度も下がってしまいます。
ドキュメントを作成する目的が適切ではない
2つ目はドキュメントを作成した目的が適切ではないことです。もっと言うと、「とりあえず文字に起こしておこう」が多いことです。
これについては必ずしも悪いわけではないと思います。教えてもらったことの備忘録や咄嗟のメモ等々、とりあえずストックしておきたい情報は少なからずあります。
しかし、そういったドキュメントの量が多い上に、それは別の場所に書いてあるのでは？という内容まで書かれていることがあったり、無題のドキュメントとしていろんな場所に点在していたりと、今回初めて見返したかも..といったドキュメントが存在しました。
このようなドキュメントの目的は、強いて言うなら「情報を書いておくこと」です。
昔の私が作ったドキュメントを見て、ドキュメントを作成する時のモチベーションが書いておかないと不安だから書くになっていることに気がつきました。
しかし、これもドキュメントが増え、情報が探しにくくなる原因になってしまいます。せっかく残しておいたのに埋もれてしまったら不安だから残しておく、の意味もなくなってしまうのです。
無駄にドキュメントを増やさないためには
このように、せっかくドキュメントがいっぱいあるのに役に立たないのはとてももったいないです。作ったドキュメントを活用するためにも、不要なドキュメントは削除し、必要なドキュメントをきちんと運用していきたいですよね。
そこで、今の私が前述のような原因に対してどう対処しているかを考え、あらためて書き出してみました。
とりあえずのメモは消しやすいツールを使う
1つ目はとりあえずメモしたい場合、消しやすいツールを使うことです。
前述の通り、私は書いておかないと不安だからとりあえず書くという理由でドキュメントを作成してしまうことがありました。
正直、それは今でもあまり変わりません。とりあえず書いておこう、と思って文字に起こすことはよくあります。
ただ、内容が多く、まとまったものになるもの以外はSlackの個人DMやTrelloなど、書きやすくて消しやすいツールに書いて定期的に見直す・消すようにしています。
そうするととりあえず書いておかなきゃ、という不安は払拭されますし、複数の場所に点在したり存在を忘れてしまったりして見返さない、といった問題を防ぐことができます。
体裁も気にしなくていいので、変に時間を取られることもありません。
私の場合は「この情報はいらない気がするけど、どこにも書いていないのが不安」と思ってしまうこともよくあるので、消しやすいツールに書く、という点もポイントです。
整理をかねて見返すことでメモとして書いた内容をあらためて読む機会ができるので、「これは他の人にも共有しておいた方がいいかも」「そういえばこの知識忘れてた」「この情報はもういらない」など、ドキュメント化する情報の最適化や情報の取捨選択がしやすくなり、無限にドキュメントが増えることを防ぐことができます。
情報の利用シーンを考える
2つ目は情報の利用シーンを考えることです。
前段にて「ルート検索APIについて仕様検討をしたときの資料が複数あった」「タイトルだけでは内容がわからずに困った」と記載しましたが、これはそもそも後で見返すことを想定できておらずその場凌ぎの命名になっていたことが原因だと言えます。
ドキュメントとして残している以上後から見返す可能性は必ずあるため、そのシーンは意識しておく必要があります。
加えて今回例に挙げた「ルート検索APIの仕様検討」なら、今後ユーザーからの問い合わせ調査で必要になるかも、他の開発者が同じようなことを考えたときに参考にするかも、といったことが考えられます。
そのような場合、プロジェクトのシステムに関わることなので、自分用の備忘録としてではなくプロジェクトの共有ドキュメントとして作成しておいた方がいいですよね。
具体的な作成例を考えてみます。
ナビタイムジャパンではAtlassianのConfluenceやJIRA、GoogleのGoogleスライド、Googleドキュメントを利用する機会が多いため、それらを用いた例を挙げます。
まずルートとなるページを1つ用意し、大筋の情報はそれを読めば把握できるようにします。今回は内容をプレゼンしたり外部に共有する必要がある内容ではないため、ページ送りやファイルを開くといった手間が不要かつレイアウトが調整しやすいConfluenceに作成することにしました。内容はプロジェクト全体に関わることなので、場所は個人用のスペースではなくプロジェクト用のスペースを選択しています。
上記のようにルートとなるページを作成した上で、検討の過程や最終的な成果物として作成した別のドキュメントはルートとなるページから辿れるようにします。それにより、初見の人でも複数のツールに情報を探しにいく手間がなくなりますし、情報の見落としも減らすことができます。上図では最終的に決まった仕様を記載している内部仕様書、他PJへの作業依頼、検討段階でプロジェクトメンバー等に共有した説明スライドなどを例に挙げました。
ちなみに、途中途中で作成したドキュメントについては「どの案件のどのタイミングで使ったファイルか」「複数ある場合、どの順番で見ればいいか」等の情報がファイル名からわかるようにしておくと他ツール上でも見やすくなると思います。
このように、共有に必要な情報を集めて辿れるようにするだけでもその案件を把握する際に必要なドキュメントを通覧しやすくなります。それにより、その案件について知りたい時はそのページを見ればいい＝その場所から辿れるドキュメント以外は把握・運用不要な状態にすることができます。
今回の例はあくまで一例であり、プロジェクト等で決まっているルールや命名規則等があれば当然それに則って作成する必要がありますが、いつ誰に読まれる可能性があるのかを考えることで必要なドキュメントを運用しやすい形で残しやすくなります。
まとめ
今回はドキュメントを大量生産しないためのポイントとして以下の2点を挙げました。
とりあえずストックしておきたい情報は1箇所にまとめて定期的に見返す
共有したい情報はいつ誰に読まれる可能性があるのかを考えてドキュメント化する
今でもドキュメントを作る上で悩むことは多いですが、仕事をしていく中で読みやすいドキュメントや参考になるドキュメントに触れる機会がたくさんあり、結果的にいいところを真似するという形で少しずつ改善できていることも実感できました。
ドキュメントは読むのもなかなか大変だったり面倒に感じてしまいがちですが、色々なドキュメントを読むことで自分が書く時に使える手法や観点が増えるので、ぜひ積極的に読んでみてください。
最後まで読んでいただきありがとうございました！