More than 3 years have passed since last update.

技術系ドキュメントの書き方の基本

Last updated at 2020-01-19Posted at 2020-01-19

ドキュメントを書く段取り

技術系のドキュメントを書きたいと思ったときにまずやること。それはネタ集めです。ドキュメントを書く時の段取りは以下の段階を踏みましょう。

ドキュメントに書くネタを集めます。ネタ集めでは以下のことをやります。

技術系のドキュメントに限らず、文章を書くときの一番の基本です。注意すべき点は、まず書きたいことを決めたとして、それを言葉で説明できることです。書きたいことを言葉で説明できないのに、ドキュメントが書ける道理がありません。

次に、書きたい事の情報を集めましょう。例えば、Linxuのコマンド操作についてドキュメントを書くとして、Linuxのコマンドと操作方法を知らなければドキュメントは書けません。ここで大事なのは、ただ知っているだけではなく、説明できる理解度が必要だということです。

最後に、集めた情報の裏付けを取ります。集めた情報に間違いがあっては元も子もありません。先ほどのLinuxのコマンド操作であれば、実際に動かしてみて、意図したとおりに動くことを確認することです。裏付けの確認をするには、どういう前提や条件が説明できるかどうかで判断できます。

集めたネタを組み合わせる作業です。書きたいことに基づいて集めネタを検討していきます。この段階で、集めたネタが足りなければネタ集めのフェーズに戻ります。集めたネタが多い場合は、どのネタを使うかを選択します。

内容の充実したドキュメントを書こうと思えば、多くのネタから書く内容を選んで組み合わせていくことになります。集めたネタは、全てドキュメントに盛り込めるとは限りません。ドキュメントに記載できなかったネタは、別のドキュメントに活用しましょう。もしくは、単体のメモ書きとしても活用できます。

構成が固まると、ドキュメント全体のボリュームが見えてきます。もし、ドキュメントのボリュームに対して要件が出ている場合は、この段階で過不足が分かります。要件を満たしていないのであれば、ネタ集めのフェーズに戻ります。多すぎる場合は、使うネタを絞り込んでいきます。

ドキュメントには以下の三つの要素があります。

これらの質を高めることで、読みやすいドキュメントが書けます。下書きでは、この三つの要素の内のドキュメントの内容を作っていきます。

まず、ドキュメントの内容は、構成のフェーズまでにまとめた情報です。技術系のドキュメントであれば、文章だけでなく図や表が必要になることもあります。構成を元に実際のドキュメントを借り組みしていくことで、内容が固まってきます。

下書きのフェーズで注意すべきは、ドキュメントの内容に集中することです。この段階ではまだまだ内容が変わることがあります。細かい言葉遣いや書面のレイアウトのミスを潰していくと、内容の変更の際の手戻りが大きくなります。また、内容と校正とレイアウトを同時にやると書く人の負担が大きくなります。

校正に関しては、知識さえあれば第三者でも対応できます。レイアウトに関しては、ドキュメントの内容よりも、ドキュメントを作成するソフトのスキルが問われます。無理にドキュメントの内容をまとめた人がやる必要はありません。

下書きのレイアウトと校正を行います。下書きでもおおまかなレイアウトや校正は行いますが、厳密におこなうのは、内容が固まった後です。ネタ集め、校正、下書きが適切にできていれば、清書のフェーズは機械的な作業になります。

下書きまでのフェーズであれば、清書で使用するフォーマットを使用する必要はありません。よく、清書のフォーマットに下書きをすれば効率が良いと誤解されます。清書のフォーマットで下書きすると、フォーマットのデータが壊れたり、改ページなどの設定のやり直しが多発して、かえって効率が落ちます。

清書したドキュメントは、基本的にあまり更新しないことをお勧めします。長編のドキュメントの場合、修正箇所が不明確になったり、内容に矛盾が発生する原因になります。誤字脱字や多少の追記であれば問題はありませんが、内容の変更が伴う場合は、変更の内容に伴いフェーズを戻して作業することをお勧めします。