お求めのドキュメントは書けません！ Part3 --なぜドキュメントを書くのがツマラナイか--

スキル | ワークスタイル

» 2015/12/14

◾︎やり方が分からないと楽しくならない

　コードは書く事が楽しいのではない。書いて思い通りに動くと楽しいのだ。ドキュメントも同じだ。まともなドキュメントが書き上がって初めて楽しいと感じる。本当に楽しいと思うためには、納得のいく結果が必要だ。

　そもそも、ドキュメントを書いて納得のいく結果が得られているだろうか？ドキュメントと言われているクソファイルのほとんどが、凄まじく効率の悪い方法で作成され、作った後でも二度と中身も見ないような代物だ。

　これでドキュメント作りが楽しくなる訳が無い。

◾︎まともなドキュメントの基準

　まともなドキュメントを書くには何を基準にすれば良いのだろうか。それは簡単だ。手近な専門書を基準にしよう。現場のドキュメント規約はいくら守ってもドキュメントを作る力は付かない。サクッと切捨てよう。

　書籍はドキュメントを書くプロが書いている。レイアウトにしても、構成にしても、ドキュメントを書く上で参考にできる部分が多くある。例えば、使用されている書式についても必要最低限に絞られていて、明確な規則のもとで使用されている。

　内容についても、高度に整理されている。表にしても、限りなく大きいものを無理やり縮小して掲載するような事はしない。セルの結合も最低限に済ませている。図解にしても、一つ一つが目的をもって書かれている。

　構成やレイアウトを学ぶのであれば、読み慣れた専門書を使って確認すると良い。

◾︎書籍と同じレイアウトを実現するには

　書籍と同じレイアウトを実現するには、ワープロソフトを使うしかない。もしくは、Sphinxのようなドキュメント生成ツールだ。でもなければ、基本中の基本である、目次すらまともに作れない。

　そもそも、ワープロソフトはドキュメントを作るためのソフトだ。使い方を覚えずにドキュメントを書こうという方が無理がある。よく、「Wordは難しい」と言われるが、それは違う。単に使い方を知らないだけだ。

　ドキュメントを作成する基本は、自由なレイアウトでは無い。いかに制約に落とし込んでいくかだ。自由なほど統一性がなくなり混沌とする。まず、ここから勘違いしている人が多い。あとは、前準備でスタイルの機能を構成する必要がある。具体的な手法については、この本で基礎を固めよう。

◾︎肝心な内容がずっぽ抜け

　ドキュメントを書いていて一番面白くないのは、対象のシステムがクソな時だ。そもそもな話、コードにしてもサーバにしても、いい加減な作り方をしていたら、ドキュメントを書いた時にいい加減さが露呈する。

　対象になるシステムがクソだと、クソドキュメントしか書けない。曖昧な表現でごまかすか、ひたすら冗長な記述を繰り返すことになるので、書いていて苦痛になる。もし正直に書いたら欠陥の解説にしかならない。

　ドキュメントを書けるようになるには、小規模なシステムで練習しよう。構成が把握できている自宅サーバあたりが丁度いいと思う。無理に難しい内容を書く必要は無い。確実に分かる内容をまとめるだけでも、かなり納得できるドキュメントが書けるはずだ。

　次回、Part4では、ドキュメントに対するレビューについて書いてみようと思う。内容はクソレビューがクソレビューたる理由をつらつらと書いてみるつもりだ。