Take IT Easy!［56］エンジニアのためのドキュメンテーション心得
── 若林健一 / kwaka1208 ──

●適切なツールを使う

エンジニアの書くドキュメントというと、Excelの列を短くしてセルを正方形にし、方眼紙のようにした「Excel方眼紙」を使う人も多いようです。

ワープロソフトの表組み機能や図形描画機能が貧弱で、PowerPointのようなプレゼンテーションソフトがなかった時代に、自由なレイアウトができる方法として重宝されたテクニックだそうです。

しかし、Excelは印刷が画面通りにでない（文字が切れる）ことがあったり、「Excel方眼紙」では罫線や背景色、セルの結合を多用するためメンテナンス性が低いのがデメリット二なります。

代替手段が多数存在するある現在では、目的に応じて適切なツールを使うことも大切です。私がどのような文書にどのツールを使うかを考える時の基準をまとめてみました。

【表計算ソフト（Excelなど）で作成する資料】

・並べ替えやフィルタ機能で欲しい情報だけ抽出できた方が便利な、データが中心の資料

・関数を使って、資料の一部を自動的に作成することができたり、メンテナンスが容易になる資料

・印刷はせずに主に画面で参照することが多い資料

Excelのデータから列挙型のデータを生成するような使い方をすれば、ソースコードの自動生成ツールとしても活用できます。

【プレゼンテーションソフト（PowerPointなど）で作成する資料】

・図や画像を貼り付けることが多く、ページ単位で印刷して利用する資料

・決まったフォーマットの中に記入しなければならない資料（テンプレートを使う）

・表組みを使うが、計算処理やデータの抽出・ソートを行う必要がない資料

私自身は、PowerPointをドキュメント作りに使うことが多くなっています。理由は、印刷に向いていることと、レイアウトが自由で画像や図形が使いやすいことですね。

表組みを使うものも、計算処理やデータ抽出を行わないのであれば、ExcelではなくPowerPointを使っています。

【ワープロソフト（Wordなど）で作成する資料】

・マニュアルのように、文章中心で章立てを組み立てたり、目次をつけることが必要な文書

最近はWordを使うことは減りましたが、マニュアルのように章、節をきちんと組み立てる文書の場合は、ワープロソフトが適しています。

【テキストエディタで作成する資料】

・リリースノートなどの簡易なもの

・Gitなどのバージョン管理システムで履歴管理するもの

Markdownを使えば、テキストエディタだけでも書式付きテキストを書けるようになりましたし、Gitのようなバージョン管理システムで履歴管理できるのもテキストファイルのメリット。リリースノートや、内部向けの開発メモのような規模の小さいドキュメントならテキストでも充分です。

●ドキュメントは、コミュニケーションツールである

ソフトウェア開発プロジェクトにおいては、ドキュメント作成は後回しにされることが多々あります。

しかし、私はドキュメントをコミュニケーションツールのひとつ考えて、小さなドキュメントをたくさん作り、その内容をレビューしながら開発を進めていくという手法を取っています。

ドキュメントを用意せずに会議をするよりも、ざっくりでもよいので書いたものを用意して打ち合わせに臨めば、テーマが明確になり、認識違いや漏れを防ぐことができて、打ち合わせの時間なども大幅に短縮できるなどよいことづくめです。

打ち合わせ結果を書き込めば、記録が確実に残りますので、これを添付資料とすれば議事録に書く内容を大幅に省略できます。

ドキュメント作成をやっかいもの扱いにせず、コミュニケーションツールとして使いこなせば、開発を円滑に効率よく進めることができるものなのです。

【若林健一 / kwaka1208】 kwaka1208@pote2.net
crossroads
< http://kwaka1208.net/
>
< https://twitter.com/kwaka1208
>
< https://www.facebook.com/kwaka1208/
>

CoderDojo奈良
< http://coderdojonara.wordpress.com/
>