読者です 読者をやめる 読者になる 読者になる

Masa / Lino Blog

Masanori Satoh ( Masa / Lino ) の徒然ブログです

本気でドキュメントを書くときに気をつけている10のこと

テクニカルドキュメントを本気で書くときに気をつけていることをまとめてみます。
一応、私は雑誌等に執筆活動もやっています。

書き始める前

1. 目次を洗い出す

ここでドキュメントの8割が決まるといっても過言ではないです。
この段階で抜け漏れ、重複を洗い出します。
特に複数人で執筆するときは特に重要です。

2. 書く内容をすべて実践する。

言うまでもないですが、テクニカルドキュメントは手を動かしてみないと書けません。
動かさないで書いてしまうと、嘘だらけのドキュメントが完成するでしょう。
テクニカルドキュメントではない場合は、全体をイメージします。

書いている途中

3. 文章は短く、シンプルに

同じことを伝えられるなら文章は短いほうが理解しやすいです。
ただ、舌足らずになるほど短くはしません。
根底にあるのはKISS(Keep It Simple, Stupid)です。
余談ですが、KISSは仕事をやるときの判断基準にもしています。

4. 主語を意識する

特に手順を紹介するドキュメントの場合、意識しています。
人がやるのか、プログラムがやるのか、ハタマタ誰かがやってくれるのか。
話し言葉の場合は主語がなくても伝わりますが、文章の場合はそうはいきません。

5. 受身文を極力使わない

これは4. 主語を意識すると連動しています。
受身文を使うと、主語がぼやけてしまう場合が多くなります。
ただ、ツールが行ってくれる処理などは受身文を使っています。
(例) Eclipseが自動生成して、ソースコードが出力されます。

6. できるだけ簡単な方法を採用する

多くの人が読むテクニカルドキュメントの場合特に意識しています。
とにかく簡単な方法で再現できるような手順を執筆します。

読む人のレベルはさまざまです。
自分が常識だと思っていることも、キチンと説明します。

7. 「だと思います」とか「私は」という表現を使わない

「だと思います」は弱気に見えて、ドキュメントの質が疑われるので使いません。
「私は」とか「筆者は」は基本的には使いません。独りよがりな文章に見えてしまいます。
「私は」を使うとすれば、コラムとか体験談を書くときだけです。

8. カタカナ英語を使うときはSunの日本語スタイルガイドに従う

私はJavaのテクニカルドキュメントを書くことが多いので、このスタイルにしています。
ただ、最近Microsoft内閣告示第二号をベースにしたルールへ原則準拠になったらしいので、変更も検討しています。

書き終わった後

9. MS Wordの文書校正をかける

書いているうちにかなり文章がゆれてしまいます。
サーバとサーバーが混在したりします。
このようなケースや助詞の使い方間違えを一括で直すことができます。

10. 心を空っぽにして、もう一度見直す

ここも重要です。書いているうちに、客観性がなくなってしまいます。
半日くらい自分の好きなことをやって、もう一度見直すと、客観的にセルフレビューができます。
心を空っぽにするにも、納期ギリギリで書かないのが重要です。