ドキュメントなんて基本、読まれない。だがそれでいいのだ。
■ドキュメントを書く技術
エンジニアなら技術と言えば、コードを書いたりサーバを構築するような技術を思い浮かべるだろう。ところで、文章を書く技術をエンジニアとしての技術と認識しているだろうか。少なくとも、今まで働いた現場ではそういう認識はなかった。
文章を書くなんて言うと、小説のような情緒的な文章を思い浮かべる人が多いようだ。あんな能力、エンジニアが持ってても役に立たないぞ。と笑い飛ばされるかもしれない。実際、とあるドキュメントの書き方の本には、そういう能力は必要無いと書かれていた。
ちなみに、私も今までに業務の引き継ぎというのを何度となくやってきた。実は、引き継ぎのためのドキュメントを小説仕立てに書いたことがある。小説仕立てに書いたことで、「これやっちゃダメ！」をやったらどうなるかがよく伝わったようだ。最終的には、伝えたい内容が的確に伝わった。
ある意味、Excel方眼紙のクソドキュメントを書くくらいなら、伝えたい内容を盛り込んで小説書いた方が伝わる。人間は理性より感性の方が、なんだかんだで優位に立つ。だったら、感性に訴えるのも一つの手段だ。
■読んでてツマラン。そりゃ読まんだろ。
人の書いたドキュメントを読むのってツマラナイよね。書いてるのは素人だ。しかも、書けと言われて嫌々書いてるような代物だ。主体性なし、書く技術なし、書いてる人は社畜で何も考えていない。そりゃ、読んで楽しいはずがない。
読んでツマラナイものなので、書くことに必要性を感じなくなる。必要性を感じないから書くことにモチベーションを保てない。ますます書くのが苦痛になる・・・。と完全に負のスパイラルが生じている。
そもそも、コードを書くプロはいるが、ドキュメントを書くプロはなかなかいない。誰でも小学校、中学校、高校と国語やってたんだ。文章くらい誰でも書けるだろ。文章書いて飯食いたければ、小説家にでもなりやがれ。と、大半のエンジニアはこういう認識ではないだろうか。
人に読ませるものなら、きちんと技術を磨いて書きやがれ、こんにゃろう。人に物事を的確に伝えるにも技術は要る。そういう技術を磨かずにドキュメントを書いて、読んでくれというのも無理がある。人に読んでもらいたいなら工夫や努力は必要だ。
■それでもドキュメントは読まれなくてもいい
なぜドキュメントは読まれないのか。それは、どんなに頑張ってドキュメントを書いても、自分の知っていることしか書けないからだ。つまり、ドキュメントを書けた時点で、その内容については把握しているということだ。
しかも、ドキュメントの完成度が高いほど、ドキュメントに書かれている内容に対する理解が深い。完成度が高いほど、自分の知っていることしかドキュメントに書かれていない。仕事というスタンスで考えれば、今更ということになってしまう。
そもそも、ドキュメントを書く時の目的を決めているだろうか。やみくもに業務を文書化しても意味は無い。整理もされていない業務を文書化したところで、読む価値も無いようなクソドキュメントが量産されるだけだ。
なので私は一般的な解釈とは違う理由でドキュメントを書く。ドキュメントを書くことで、自分が業務を理解しているかが細かくチェックできるのだ。これは、既存のドキュメントをメンテナンスしたり、自分仕様にカスタマイズすることでも目的が達成できる。だから、書いたものが読まれなくても良いのだ。
■読まれる価値のあるものを書く難しさ
IT系のエンジニアであれば、技術書の一冊や二冊は読んだことがあるだろう。あれ一冊を書くのには相当な手間が必要だ。少なくとも、業務の合間に書けるような代物ではない。それだけ、完成度の高いドキュメントを書くのは難しい。
まともなドキュメントを書こうと思うなら、一般的に考えられているより、かなり高いレベルの能力が求められる。それを万人に求めるのは難しい。人に読ませるドキュメントを書くより、自己チェックの手法としてドキュメントを書くという方が現実的だ。
そもそも、十分に自己チェックが行き届かないと人に読ませるようなドキュメントを書けるはずもない。一般的には、自己チェックをすっ飛ばして、いきなり高品質なドキュメントを書こうとするから失敗する。
自分の書いたドキュメントなんて読まれなくていいのだ。とりあえず書こう。そして、必ず読み返そう。これを繰り返すことで、考え方が整理されていくのに気づくはずだ。これをやらないと、人に読ませるようなドキュメントは書けない。
考え方を整理できないと、ちょっと複雑な仕組みになるとすぐに破綻する。思考能力を鍛える一環として、訓練としてドキュメントを書いてみてはどうだろう。日本語をまともに使えるだけの知能は、技術を支えるバックボーンとして有効だ。たかが日本語と舐めてかからず、向き合ってみてはどうだろうか。
コメント
天狗の高下駄
>自己チェックの手法としてドキュメントを書く
困ったことに、文章を書くのが苦手な人は「これは俺が知ってて当然だから」、「これは常識だから」といった理由を捻り出して自分基準で色々文言を間引きするので、内容がスカスカになりがちなんです。
個人的な考えですが、1週間後、1か月後、3か月後に自分が書いたドキュメントを読み返して、自分自身が理解できるかどうかまで確認してもらえたら嬉しいんですが。(書いた本人が理解できなきゃ意味ないですから)
Anubis
--天狗の高下駄 さん--
どうも、Anubisです。
頂いたコメントを読み返してみて、ドキュメントを見ることで、書いた人の性格判断ができるなと思った。初っ端から書かない人の場合、その理由を聞けば考え方が分かりそうだ。
志御
はじめまして。
ドキュメントが書けないエンジニアは多いですよね。
でも、そもそも何故、ドキュメント（要件書、設計書）を書く必要があるかが重要だと思います。
以前、オフショアするプロジェクトに携わったことがあるのですが、その時は、オフショア先のエンジニアにプログラムを書いてもらう為でした。
もちろん、コーディングだけではなく、プログラム設計もオフショア先には期待していたので、設計書の他に要件書と議事録も渡しました。
自分としては、システムを作るために必要な情報とシステムがどうなっているべきかの想定を、「伝える」ためにドキュメント化すれば良いと思っています。
引き継ぎの話を言われていましたが、そもそも本来の伝えるためのドキュメントがあれば、それを渡すだけで引き継げるはずです。
多くのエンジニアがドキュメントを読まないのは、ドキュメントに書かれている内容が、不足していたり、不備があったり、正しい日本語で書かれていなかったり、情報が整理されて難解である為です。
書き方が下手なのではなく、情報として何をドキュメントに表現しなければならないのかがわからないのだと思います。
あとついでに、多くのエンジニアは、「仕様」と「設計」を混同しています。
前者は、システムはどうなっているべきかであり、後者はシステムの作り方です。
すみません、好き勝手に書いてしまいました。