ドキュメントに関する社内講義の準備

お仕事で少し新人さんに説明をする必要があるので、方針を考えておくメモ。ちなみにあんまり深いものではなく、上っ面のポイントだけにしようかと。深いところについて語るとほかの同僚さんたちと衝突しかねないし。

NGなパターンについてはいくつかサンプルを土日で用意しておこう。過去のひどい文書を掘り出せばいくつか出てくるカモ。

……と思ったけどやめた(2016/07/24加筆修正)。自宅で仕事するのばからしい。既に20時間以上も自分の時間潰してるのをこれ以上増やしたくないので（サービス残業的なものをやるのって20年近くの仕事歴でここ2年が初めてかもな…）。

基本の基本

偏っているかもしれないけれど現時点で思いつく基本の基本。

文章構成に気を配る。段落、章立て、文脈等。
文章の体裁、文体を統一する。文末をいいきりにするのかどうか、などをそろえる。
箇条書きの場合も、各箇条で文体や構成をそろえる（名詞で終わるか、動詞で終わるかなど）。
初登場する略語については必ずどこかで説明を入れる（以下、～と略す、などの記載があればよい）。
可能であれば略語は使わない方針を検討する（読み手が不特定である場合はなおさら。また、業界や文脈によっては別の略語と混同するものは紙面の都合や見た目上の問題が無い限り、極力利用を避ける）。
読んでほしい肝の内容をなるべく早く読み手に伝える（仕事の文書の場合）。
読み手に合わせた内容にする。前提知識などの有無を考え、必要であれば内容を簡単にしたり、説明を加えたり。また、前提を満たす読み手のみに限定できる場合は過剰な説明にならないようにする。
助詞の使い方。一つ間違えるだけで意味が変わったりわからなくなるし、ひどいと資料自体の信頼性が落ちて読んでもらえなくなる。
同じ意味で異なる表現が出来る言葉は文書内で統一する。

ツールが持つ機能を使ったレイアウト

後のメンテナンス性につながる話。とりあえずメモしておきます。ほかにもあるよね。

センタリングや右寄せに空白を使わない。
改行は改行を使う。空白で次の行までずらさない。
ページ切替も機能があればそれを使う。空行などで調整しない。
目次や索引を手作業で作らない。手作業にならざるを得ないのであれば、自動生成できるツールでの文書作成を検討する。

閲覧者のことを考えたレイアウトや構成、記法

読み手のことを考えない資料作成はNGです。

見栄えをおろそかにしない。酷い場合、最悪、読んですらもらえない。
文章の横幅を改行で調節しない。段落はなるべく1行で記述する（閲覧者が使うツールをリサイズした際に、自動的に1行の内容が調整されるようにするため）。
色や太字などに一定のルールを持たせる。ルールに説明が必要であれば説明を併記する。
半角の日本語文字（1バイトのカナなど）の利用は極力避ける（全角サイズのカナと混在する可能性があり、見た目を損なうので……昔は海外の環境で読めないとかいろいろあったのですけどね）。
半角英数字記号、全角英数字記号の混在は極力回避する。迷った場合、印刷する文書であれば印刷時の見栄えを優先する。

画像の取り扱い

プレゼン資料などで使う画像の取り扱い、無造作に扱うと地味にドキュメント関連作業に支障が出ます。

貼付画像の種類、画質を適切に選定する。画面上で見るのか、拡大される可能性があるか、印刷するのか（カラー？白黒？）などによって適した種類を選定する。
画像の画質を適切に選定する。画像フォーマットについても同様。各フォーマットの特性を大まかに把握し、ふさわしいものを選ぶ。
リンクした画像などの場合、資料の配布や別環境での閲覧が可能か検討する。
画像の出自に注意する。著作権的な問題はないか、個人情報をいい加減に扱っていないか（個人の顔や姿、名前やその他情報が画像に含まれないか）。

メンテナンスを考慮した作り

一発ものの資料であればどうでもよいのですが、繰り返し手を入れていくような資料である場合、最初の書式やつくりがそのあとの作業時間に大きく影響することがあります。これは用途に応じてさじ加減の調節が必要です。速度優先の場合はすべてをなげうって「見栄えと内容Only」で作ることもあり得ます。

追記が容易であるかどうか。
- レイアウトが前述のツール機能で実現されている。追記することで改行やページ切替が大きく崩れない。
- 目次や索引といった通番を振る必要があるものの作り直しが発生しないかどうか。目次が必要な場合、目次を自動生成できるツールを最初に選定する。
- 図番号や表番号についても同様。後から数百ページの資料の番号を手作業で打ち直す、なんてことが無いように。
貼付素材などがそろっているかどうか。
- 画像などを貼付する場合、その内容を将来描きかえる必要が出た際に容易に編集できるように準備しておく。
- 画像がそのまま貼付されている場合は良いが、別のところでソースが用意されている場合は、その所在が分かるような状況を作っておく（Visioで作成した図をEMF形式で貼り付ける場合など）。
ツールの選定に注意する。
- ドキュメント作成ツールが入手可能であるか、将来の編集者にも用意できるかを考慮する。
- 難しい場合にはツールの長期保管（ライセンスやメディア等）に留意したり、いっそのことテキストファイルなどのようにどこでもだれでも編集できる形式を選定したりする。

Excel固有の話

セル結合は極力さける。あとあとのメンテで大変になる（結合してると行挿入できなかったり、いちいち解除して…などの手間が出る）。
長期利用する文書を方眼状態のExcelで作ることはできるだけ避ける。やむを得ない場合、利用ルールをきちんと統一する。
記述を横方向に広げず、上下方向に伸ばしていく。何が言いたいかというと、追記や加筆する際には下へ、下へと追記できるようにすることで、直感的に訂正したり読み進められるようにする。横に広げることもExcelならば可能だが、1画面に収まらなくなる上、読み手、修正者に混乱を招く。
ヘッダーはできればテキストボックスなどのオブジェクトをつかう方が良い。ヘッダーを描くためにセルのサイズなどが固定されるのは本末転倒（文書の本体は文章！ヘッダーではない）。オブジェクトにしておけば、セルの横幅は自由に変えられるので、シートの内容ごとにセルの構成を変えることができる。
Excelで設計資料などを書く際は、読み手が読めるのは1シートだけであることに留意する。WordもExcelも、縦方向に画面を分割して表示する機能があるが、Excelの2シートを同時表示する方法は無い。従って、「シート2に画面レイアウト」「シート3にその説明」といった書き方になっている場合、二つを並べて見比べることは出来ない。できれば、1シートにまとめて「上に画面レイアウト、下に説明」といったスタイルにすると読み手がわざわざ印刷したりしなくても一度に読めるようになる。