ウノウラボのyukiさんが「ドキュメントを楽しく楽に書くために」という記事を書いておられる。僕も少し思うところがあるので書いてみる。
ここんとこ、シゴトでのドキュメント書きの比重が高まっている。内容は、Javaで書かれたツールの設計についての解説。使っているのはEmacs（Meadow）、日本語入力はSKK。SmartDoc形式で書いて（sdoc-mode使用）、HTMLとpLaTeX2e経由でのPDFを出力としている。キーボードはFKB8579。この環境でのドキュメント書きがけっこう楽しく進んでいる。楽しい要因として、次のようなものがあるんではないかと考えている。
安定し、慣れ親しんだツールを使っていること
ふだんのJavaコーディングにはEclipseを使っている。そのEclipse内でJavadocコメントを書いてるのと比べると、Emacsで日本語の文章を書くのはとても心地が良い。さすが専業テキストエディタだ。Emacsは使いはじめて10数年、SKKとの付き合いも8年近くになる。SmartDocを使うのは少し久しぶりだったけど、以前ためたノウハウは有効だし、sdoc-modeもすぐに感覚を取り戻した。キーボードのタッチはいつもどおり良好。ほぼストレスゼロでキー入力が進んでいく。すばらしい。
僕の場合、たまにどうしてもWordで書かなきゃならない時があると、何か困ったWord機能が発動しないかとヒヤヒヤしてしまってとても精神的苦痛が大きい。勝手知ったるEmacs+sdoc-mode+SKKでの記述がこんなに快適だったかと、あらためて認識した次第。ツール重要。
出力がキレイで、すぐに確認できること
SmartDocのHTML出力用には青を基調とした独自CSSを使っていて、これがなかなかよろしい（デフォルトのもキライじゃないけど）。SmartDocを書きつつ、C-cC-cでサクッとフォーマットしてブラウザで確認すると、さっき書いた文章がキレイなHTMLになって表示される。これが嬉しい。
さらに、pLaTeX2e*1を経由したPDFも文句なしのキレイさ。自分の文章がプロが作った本みたいにレイアウトされるのもまた嬉しい。こういう嬉しさは重要だと思う。
ちょっと話がずれるけど、Javadoc*2も標準Docletで処理するだけでけっこうキレイだし便利に使える。ただ、手元で処理するとけっこう時間がかかるからなかなかやんないんだよね。そのままだと、誰も見ないからってことで書く気が失せてしまいがちだ。そこで、常時最新のJavadocを生成するサーバを用意して、チーム全員がいつでも最新のJavadocにアクセスできるようにしておけば、自分の成果も見えやすいし、他の人からも利用しやすいということで書く気力がわいてくるんではないかな。ペアプログミラングじゃないけど、他人の目も利用しよう。
書く対象が良いものであること
いくら良いツールでキレイな結果が出ても、書く対象がヘボいものだとやはり精神的苦痛が大きくなってしまう。「苦しい説明を余儀なくされる」というか。
僕がいま書いている対象のJavaプログラムは、自分で言うのもなんだけどそれなりにキレイに設計できているから、わりとすんなり説明が書ける。でも、ドキュメントを書いて初めて不自然な点に気付いて、設計やクラス名を見直したケースもある。
普段から説明することを意識した設計をしたり、Javadocをちゃんと書くなりしておくと、いざまとまったドキュメント化が必要になった場合もすんなり説明できるプログラムになる。実はこれがいちばん重要かもしんない。
というわけで
僕がドキュメントを書くのを（それなりに）楽しんでいる要因を3点ほどあげてみた。慣れ親しんだツールを使って、良いものについて書き、キレイな結果を得る。そうすれば、苦痛が減って、楽しさが増える。めでたしめでたし。
