エンジニアのためのWord再入門講座 : 賢者の図書館 (Under Construction) : livedoor Blog（ブログ）

エンジニアのためのWord再入門講座美しくメンテナンス性の高い開発ドキュメントの作り方

キーワード：
　佐藤竜一、Word、ドキュメント、エンジニア、スタイル

Wordを使用し、読みやすくてメンテナンス性が高いドキュメントの作成方法が示されている本。以下のような目次となっている。

第1章　ドキュメント作成の意味とは

第2章　これだけはやっておきたいWordの初期設定

第3章　スタイルを理解することから始めよう

第4章　 DRYで行こう!

第5章　テンプレートを設計する

第6章　図と表の取り扱い

第7章　チームでの作業を効率化する
(目次から抜粋)

システムエンジニアが仕事で設計書などのドキュメントを作成するときに、なぜかWordではなく、Excelを使用したりする。そのときは、Excelのセルを正方形にし、方眼紙のように使うことがある。しかし、本書ではそんなドキュメントは見た目が悪いし、改行処理などのメンテナンス性が著しく低下するので、まともなドキュメントではない、と示されている。

そして、この本の著者の主張を一言で強烈に!?示すと、以下のようになる。

EclipseやEmacsを自分専用にバリバリカスタマイズするくせに、Wordは初期設定のまま使用し、しかもスタイルの機能もうまく使いこなしていない品質の低いドキュメントを作成していて、プロのエンジニアとして恥ずかしくないのか!!

ということだと思った。いやー、この本を読んで、いかに自分がWordを使用したドキュメント作成ができていないかがよくわかった・・・。自分の今までのドキュメント作成方法は、ぜんぜんダメじゃないか!!と思った。

この本で示されている内容は、『読みやすく、体裁が整っていて、メンテナンス性も高いドキュメントを、より短い時間で作成するための技術と考え方 (pp.iii)』とある。そして、本書では、ドキュメント作成にWordを使用することを薦めている。なぜWordかは、以下のように示されている。

　その理由は簡単です。現在のシステム開発の現場で、おそらくWordはもっとも広く使われているワープロだからです。少なくとも、大多数の開発者が使うPCには、Wordの何らかのバージョンがインストールされていることが期待できます。
　本書の説明は、その大部分がWordに特化したものです。Wordの機能の説明に終始してしまっている章もいくつかあります。しかし本書で最もお話したいことはWordの使い方ではなく、Wordを使ううえで、そしてよいドキュメントを作成するうえでの背後にある考え方です。すべてではありませんが、それらの考え方のいくつかは、他のソフトウェアにも応用できるはずです。
(pp.025)

Wordで設計書などのドキュメントを作成する理由は、それらお客様への納品成果物をWordで、と指定されることが多いからという側面もある。また、複数SI企業が参画する大規模プロジェクトでは、各社が独自のソフトを使うと他社にドキュメントを展開するときに困るので、やはりWordが使われる。このような側面からも、Wordでメンテナンス性の高いドキュメントを作成できなければならないということだろう。

本書では、よいドキュメントとは、ドキュメントにまつわるコストを最小化できるものと示している。そして、よいドキュメントは、以下の3つの条件を満たすものだとある。

読みやすい
体裁が整っている
メンテナンス性が高い

まずは、内容よりも見た目が重要、ということらしい。見た目が悪いと、読む気が起こらないからということになる。これはブログの文章でも同じだと思う。だらだらと長文で空白や改行がまったくないものだと、開いた瞬間に読まれることなくスルーされる。

また、メンテナンス性が求められるのは、完成したシステムにメンテナンスが必要なように、ドキュメントも同じようにメンテナンスが求められるからとある。つまり、変更されたシステムの内容を、ドキュメントにも同じように反映するために繰り返し改訂・追記がされるので、ドキュメントのメンテナンス性が低いと、いずれ陳腐化して役に立たないものになってしまうからとある。これはもっともだなぁと思った。

Wordなどのワープロでやってはいけない例が以下のように示されている。

「段落」という考え方を理解しない
改行を「行の区切り」だと認識する
段落の先頭に1文字の全角空白を入れる
スペースでドキュメントの整形を行う
箇条書きを実現するために手で「・」を打つ
手で連番を打つ

どれもやったことありすぎで、自分のWordの使いこなし度がよくわかってしまう・・・。これらは、すべてメンテナンス性を損なう方法なので、Wordの機能として用意されている『スタイル』を使用してドキュメントを作成するべきとあった。

スタイルを使うことの最大のメリットは、ドキュメントの各構造の外観を、常に同一に保つことができるとあった。そのため、「選択した領域のフォントを手で変更する」とか「ルーラーで個別にインデントを付けを行う」といったことはする必要がなくなるし、著者によれば、高機能ワープロがあるのにそれらのことを行うのは、職務怠慢に等しい行為とあり、かなり耳が痛い・・・。

この本を読むと、自分がいかにダメなドキュメント作成者であるかを思い知らされた・・・。ついつい簡単なドキュメントはExcelで作ったりするし、Wordを使うと、ルーラーで行位置をいじったり、空白を多用しすぎたりと、反省することばかり・・・。

WordはWYSIWYGなワープロソフトなので、あんまりWordの機能を深く知らなくても表面的に使いこなしているようには見える。しかし、ドキュメントのメンテナンス性を考慮するには、スタイルやフィールド、テンプレート、図表の取り扱いをしっかり理解しなければならないようだ。

案外自分はWordの機能を深く理解していないなということがわかった。特にスタイルとかまったくいじったことがなかった。他にもフィールドの機能とか。以下のように表中にフィールドを設定すると、Excelのように簡単な計算ができるたりする。

平均列と合計行の設定をフィールドで実現している。Excelの関数とは違い、Wordのフィールド独自の関数が用意されているようだ。そして、フィールドの計算結果を反映させると以下のようになる。

Wordにこんな機能があるとは知らなかった。フィールドは一般的に、文章中に他の部分を引用するときに使うらしいが、このように表に設定すると、簡単な計算ができる。

Excelやパワポはそれなりに使いこなしているが、Wordはどうも苦手だった。これからは、メンテナンス性の高いドキュメントを作成できるようにならなければプロ失格だねぇ。

この本は、エンジニア向けなので、Wordの機能説明は結構簡略化されている。そのため、あまりWordの機能を知らなさ過ぎる人が読むと、ちょっとちんぷんかんぷんかもしれない。自分はもっとWordの基本機能を学習してからこの本を読むべきだったと思う。どうも機能説明を読んでいても、頭にすんなり入ってこなかったので。

プロのエンジニアの人は、ぜひ読んだほうがよいと思う。案外Wordを使いこなしていないということに気づくから。