はじめに
テクニカルライティングでは、なんらかの技術を解説することが多いものです。そのとき、いっぺんに全てを説明しようとしていませんか？ それをやってしまうと、一度に大量の情報を受け取った読み手は消化不良をおこしてしまいます。情報の奔流に溺れてしまうでしょう。最初は想定している読者にすっと受け取ってもらえるサイズの情報量から始めて、それからだんだんと情報を増やしていくような書き方をするとよいです。
そういうちょっとずつ情報を増やしていく解説のやり方の1つとして、今回は簡単な話から初めてステップアップしていくというパターンを紹介しましょう。
対象読者
- テクニカルな文章を書いている人／書かなきゃならなくなった人
- その中でも、とくにソフトウェア開発に関わっている人
テクニカルライティングの領域は広いですけど、この連載ではソフトウェア開発に関連した文書を主に想定しています。
解説とリファレンス
本題に入る前に、ちょっと寄り道。「技術解説」と「リファレンスマニュアル」は、どちらもテクニカルライティングではありますが、想定読者が違います。
- 解説：まだ分かっていない人に理解してもらう
- リファレンス：もうだいたい分かっている人が参照する
ここで話題にしている「いっぺんに全部を説明しても分からないよ」というのは、技術解説の場合です。リファレンスでは逆に、正確な話だけ網羅して書かれている方があちこちページをめくらなくて済んでありがたいのです。
以下に「リファレンスマニュアル」の意味を紹介しておきます。IT用語辞典 e-Wordsからの引用です。
リファレンスマニュアル (reference manual)～IT用語辞典 e-Wordsより
製品に添付される文書の一種で、対象の機能や仕様などを網羅的に解説したもの。「マニュアル」を省略して単に「リファレンス」と呼ばれる場合が多い。
構成要素や機能や仕様、使い方などを詳細に解説した文書で、基本的には最初から順番に読むものではなく、必要に応じて知りたい項目を参照するために用意されている。詳細な使い方を知りたい場合や、対応製品の開発を行なうために厳密な仕様を知りたい場合などに使われる。
このようにリファレンスはすでにだいたい分かっている人が必要に応じて知りたい項目を読むものなので、まだ理解していない人が読むには難しいものなのです。プログラマーが渡された仕様書を理解しにくいと感じるとき、それはその仕様書に仕様の解説がなくてリファレンスだけになっているせいかもしれません。「仕様書は解説とリファレンスから構成されているべき」というのが私（＝筆者）の持論ですが、その話はまた機会があれば。
さて、それに対して技術解説は、その技術を知らない読者に理解してもらうために書きます。知らない話をいっぺんにまとめて突き付けられたのでは、理解するのは難しいでしょう。なんとか理解してもらいやすくする工夫が必要です。その工夫のひとつが、簡単な話から始めて難しい話へステップアップしていく書き方です。
