ドキュメントが更新できない理由

技術動向

» 2018/01/22

絶対的情報量が多すぎる

思えば紙を使って仕事をしていた時代は良かったのかもしれない。紙は劣化するので、作成したドキュメントは書き直されたり追記されたりと、自然に行われていた。また、手書きなので複雑な書式で書くことが難しい。欠点のようだが、複雑に書けないが故に自然にシンプルで分かり易い形にまとめる習慣がついていたのかもしれない。

アウトプットできる情報の量が少ないので、手元に存在する情報の量も少なくなる。一見、乏しい情報を元に考えるので、思考の効率が落ちそうな気がする。しかし、一つのテーマに対してじっくり考える時間が取れるので発想がクリエイティブだった。情報の量が多いということは、その分、処理をするのが大変になるということだ。アドバンテージになるとは限らない。

当たり前だが、少ない情報を整理するより、多くの情報を整理する方が大変だ。ドキュメントを更新する難易度は高くなる。理屈上、知ってさえいればドキュメントは更新できる。しかし、実際は情報を整理しなければ更新できない。情報を整理する難易度が計算から抜けるので、正しく難易度を把握できなくなる。なので、実際にやろうとすると更新できないのだ。

ドキュメントをまとめる時、多くの情報を網羅するほど良いとされている。しかし、多くの情報を網羅するということは、それだけ整理するための労力がかかる。解決策としては、管理する情報に優先度をつけよう。管理する情報の量を際限なく増やせば、ドキュメントが更新できなくなるのは当然だ。

情報が整理されていない

内容が整理されていないドキュメントというのは、更新するのに手間がかかる。ついでに、置き場所も整理されていないと探すのに手間がかかる。更新する内容が分かっていても、内容が整理されていなければ更新箇所を絞るのが難しくなる。何より、分かりにくいドキュメントは更新する気が失せる。更新されなくて当然だ。

ドキュメントを作成というと、何故だか網羅する情報の範囲を広げたがる。その結果作成されるのは、芸術品のように複雑な幾何学模様のような構成図だったり、端が見えないほどに巨大化した表だ。こういうドキュメントを作っても、大変さのアピールにしかならないので役に立たない。むしろ、仕事の難易度を上げるだけなので作らない方がマシかもしれない。

複数のファイルを分けてしまうと、逆に整理がつかないと考える人も多いだろう。しかし実際は、更新頻度の高い情報と低い情報を分けて管理できるので、思うより多くの情報を管理できる。一つの表にまとめていると、更新頻度に関係なく全部を更新することになる。しかも、一回の更新作業の手間がかかる。

情報を整理するという意味を間違えている人が多い。これは、必要な情報にすぐにアクセスできるようにすることで、情報を詰め込むということではない。情報の一元管理というのも同じだ。やりたかったら、Excelで無駄に大きな表を作るのでなく、相応の業務システムを導入しよう。Excelだけでは機能的に無理だ。

ドキュメントを作る技術が低い

ドキュメントを書く時に何のソフトを使うか選択しているだろうか。これによって、求められる技術のレベルが大きく変わってくる。テキストエディタでよければ、キーボードを打てる人なら誰でも使いこなせる。レイアウトまで求められれば、Wordを使いこなす技術が必要だ。最近では、マークダウンという選択肢もある。低い学習コストでレイアウトが整うのでお勧めだ。

ソフトウェアを使いこなす技術が無いのに完成度の高いドキュメントを作ろうとすると、ExcelやPowerPointといったソフトを使用する傾向が強い。ソフトを使用する理由は配置の自由度の高さだ。画像なり表なり、簡単な操作で好きな位置に配置できる。それが逆に仇になり、メンテナンス性が極端に落ちて更新できなくなる。

レイアウトの自由度の高さ故に、ドキュメントが簡単に作れると思い込むと最悪だ。メンテナンス不能なドキュメントが大量生産されて収集がつかなくなる。しかも、レイアウトの自由度に任せて好き放題やると、統一感がなくなりドキュメントの質が落ちる。見て分かりにくい上にメンテナンスもしにくいので、作った割に役に立たない。

簡単さを求めるなら、いっそテキストで書く方がいい。ソフトの使い方より内容に集中できる。しかも更新がやり易く再利用性も高い。無理に体裁を気にしても、具体的に文章に落とせないくらいにしか情報をまとめきれないのであれば、どのみちまともなドキュメントは書けない。ソフトウェアの自由度の高さに頼ると、余計にメンテナンス性と可読性の悪いドキュメントになってしまう。

ドキュメントの用途を誤解している

ドキュメントを書く時にどういうものを想定しているだろうか。普段からドキュメントをこまめに書く人なら分かると思うが、業務体系全てを網羅することはまず無理だ。たとえ網羅したとしても量が多くなる。全てを読むだけでも時間がかかるし、理解して実践できるようになるにはもっと時間がかかる。そもそも、書くのには更に多くの時間を要する。良いドキュメントを書くには計画性が大事だ。

ドキュメントを書いたからと言って、書いた時間分の利益がどう出るか説明できるものでもない。実のところ、書かなくても仕事はできる。経験則からすると、ドキュメントを書かない組織というのは、情報が錯綜してひどく効率が悪い。しかし、各個人は情報を押さえているので、「ドキュメントを書かないから効率が悪い」と説明してもなかなか納得しない。

かと思えば、ドキュメントに異様な完璧さを求められることも多い。これさえ読めば初心者でも熟練のエンジニアと同じ動きができるようにと、本気で要求されることもある。確かに、経験や判断も細かく分解していけば、理論上はドキュメントに落とし込める。だがそれは、辞書を書いて丸暗記すれば外国語が話せるというのと同レベルの発想だ。それができれば誰も苦労しない。

ドキュメントの用途は「業務に使う情報をまとめたものだ」と簡単に集約できる。簡単に集約できるが故に、勝手な解釈が付け足され易い。ドキュメントを書く本当の意味は、実際に行動した人でなければ理解できないと思う。だから、書け、読め、使え、そして考えろ。机上の空論だけでは説明がつかない。作ることの意味を理解できないからドキュメントが陳腐化しても更新できないのだろう。