ドキュメントなんて書いてるから炎上するんだwww

スキル | 技術動向 | 業界動向

» 2015/09/28

■ドキュメントを読んでも何も分かりません

　サーバ構築案件等の成果物として、必ずと言っていいほどドキュメンントが含まれている。提出用のドキュメントを作成していていつも「これ、もう二度と読まれる事はないだろうな」と思う。実際、過去の納品物のドキュメントを読んでもサッパリ意図が伝わらない。知りたいのは設定値ではなく、意図と経緯だ。

　まず、ドキュメントの質が低いこともあるが、ドキュメントの用途が練られていないように思う。求められるドキュメントが、素人の考えた「ぼくの最強マニュアル」でしかない。作って終わり。作った方も訳が分からない。作れと言われたから作っただけ。双方、何も得るものが無い。

　タイトルにも書いたように、そんなドキュメントを作ってるから炎上するのだと思う。そもそも、ドキュメントは仕事の道具であって目的では無い。お客さんに提出を求められると、提出することが目的になってしまい、本来の意図からかけ離れてしまう。

　残念なことに、大手ほどこの傾向は強い。営業の作る資料も、エンジニアの作るドキュメントも、仕事のできないオッサンのお守りにしか活用できていない。オッサンのお守りの為に作られたドキュメンントなど、エンジニアが読んでためになるとは思えない。

■必要なのはドキュメントではなくデータだ

　散々ドキュメントに関するコラムを連投した後に「ドキュメントなんて書いてるから炎上するんだ」とタイトルを付けたのは理由がある。ドキュメントは、わざわざ手を動かして書くものではなく、集めたデータから自動生成して、書式を整えて一文加えて終わり。このくらいのレベルで作るものだと考えている。

　勘違いしている人が多いと思うが、まずはデータありきだ。データはドキュメントを作るためのネタだ。ネタもなしにドキュメンントが書けるはずがない。ドキュメント以前に、問題の洗い出しすらできないと思う。実際、ネタを揃えずに～書を書いてる現場では、後からいろいろ問題が起きていた。

　進捗表に記入したいがために、前準備をすっ飛ばしてドキュメント作成に取り掛かるから炎上する。そういう人には、「ドキュメントなんて書いてるから炎上するんだ」くらいの表現で言わないと理解できないと思う。まず、データ集めて整理しろ。だからこのタイトルだ。

　データが揃っていれば簡単にドキュメントは作れる。コピペして書式を整えて、一文付け足せばそれで終わりだ。新人に任せて数時間で終わる。そのくらい簡単な作業だと思っている。ネタを揃えずに書くから大変な作業になるのだ。

■ドキュメントじゃなくデータ見て仕事しろ

　仕事で必要なのはドキュメントではない。あくまでデータだ。ドキュメントにしても、裏付けがどれだけあるか、具体的な裏付けとしてのデータが無ければただのメモだ。

　どんなに詳しく、分かりやすく書かれていたとしても、裏付けのデータが無ければドキュメントとしての価値は低い。そもそも、手元のデータが整理できていなければ分かりやすいドキュメントは作れない。誰でも読んで分かりやすいドキュメントは、裏を返せば大した内容が盛り込まれていない。

　全てのデータがドキュメントに網羅されているというなら、前庭としてドキュメントの作り方を間違えている。十、データを集めて集計、項目を絞って、五まで圧縮する。圧縮した五から、伝えたい意図に沿ったものを抽出して二か一にまとめて書式をつける。十の内容を書くために十の情報を集めるようなやり方では、まともなドキュメントは作れないはずだ。

　ドキュメントは最終出力だ。最新出力には成り得ない。抽出したデータを取捨選択しているので、全ての情報は含まれていないはずだ。分かりやすくするために削ぎ落されている。削ぎ落されたデータは、元のデータを見なければ分からない。現状は、実物を見るか人に聞かなければ分からない。

■データを制せ！

　このコラムでドキュメントとは、客に提出する最終出力の事を言っている。一般的には、メモで残したテキストファイルや、Excelで書いたリスト形式のデータ等もドキュメントと呼ばれることもある。ただ、このコラムでは意図的にそれをドキュメントとは言わない。精査すべきデータの一つととらえている。

　まず、私の言ったやり方、多くのデータを精査して絞り込んでドキュメントを書く。それをやってる人がほとんどいない。仕事の効率化と称して、必要な手順をショートカットしているのが普通だ。そんな人たちからすれば「データ？それドキュメントのことだろ」となって、私の言ってる意味が通じないと思う。

　ドキュメントはうんこだ。食べ物を食べて、消化して、最後に残ったカスだ。データという食べ物を食べ、分析という消化作業をして、最後に出たカスがドキュメントだ。食べ物もないのにうんこは出ない。消化できなければ、そこから何も得られない。プロジェクトに必要なのは、分析して得られた結果だ。これが栄養だ。ここまで正常にできていれば、勝手にうんこは出る。

　ドキュメントで炎上する大手SIerとそのお客さんに言いたい。お前らの仕事はうんこだ。最後にブリッと垂れたカスで仕事できると思ってないか？お前らの求めてる成果物って、実はうんこなんだよ。エンジニアにうんこを渡せば仕事してくれると思ってないか？そんなやり方だから、正真正銘、クソドキュメントしか書けないのだ。

　エンジニアなら、データを集めて分析し、そこから信頼できる結論を導きだそう。それがきちんとできているなら、ドキュメントは簡単に書けるはずだ。ドキュメントを書くのがエンジニアの仕事じゃない。結果を得るのがエンジニアの仕事だ。