【テクニカルライティング】自分の文章をすべて読ませないための技術
私達は小学校以来、国語の時間に作文や小論文を習ってきましたが、私はエンジニア１年目にその概念を覆す技術を学びました。
仕様書やマニュアルを作成するためのテクニカルライティングの技術です。
この技術は、その後も継続して書籍などで勉強していますが、技術文書での表現の本質は「文章の構造化」にあるように思います。
このノウハウは技術屋としての強力な武器になっているため、今回の記事でご紹介します。技術系の皆様はもちろん、それ以外の方も、こんな方法があるのかと参考になれば幸いです。
この技術は、説明書、仕様書、報告書などで使うと強力ですが、文学作品やエッセイなどの読んで楽しむことが目的の文章や、カタログや履歴書などの濃度が勝負の文章では最弱です。
この記事は技術文書ではないため、構造化の手法は使っていません。
余韻 vs 拾い読み
国語で学ぶ文章は、書いた内容すべてを読者に読ませ、読者に余韻を感じさせるための技術だったと私は理解しています。
テクニカルライティングは、読者が必要な情報だけを拾い読みさせる技術、つまり、読者にとって不要な文章をできるだけ読ませないように構成する技術だと認識しました。
技術文書は、読む行為を楽しむのが目的ではありません。
同じ情報を得るならば、読む文章の量が少ない方が良い一方、簡潔すぎると情報が足りず、読者に試行錯誤を強いることになります。
簡潔さと情報量のバランスをとる方法が、文章の構造化だと理解しました。
段落の構造化
構造化の手法で最も特徴的なのは、段落内の構成方法です。
１つの段落は、１つの主題文と複数の補足文で構成します。
ある段落で伝えたい内容を決め、その要約を主題文として冒頭で述べます。それに続く補足文では、主題文のテーマに沿って内容を詳細化します。
最後のまとめの文は原則として書きません。
ここで重要なことは、補足文で説明する詳細が、主題文の範囲を超えてはならない点です。
例えば、「アプリはキーボードで操作します」と主題文で書いたとき、補足文でボタン操作について言及するのは避けるべきです。
必要な場合は、主題文をより大域的な表現に書き換えるか、ボタン操作を別の段落に分離するなどの対処が適切です。
これにより、読者は主題文から事前に段落の全体像をつかめるため、補足文を理解しやすくなります。
また、読み返すときは、段落の冒頭だけで段落の必要性を判断できます。
仕様書では、補足文を箇条書きにする方法も有効ですが、この場合、箇条書きの内容を主題文で要約することになります。
複数の段落の構造化
章立ての際、項や節の内部は、複数の段落で構成されますが、段落同士も主題文で要約をまとめます。
各段落で言及できる範囲が、主題文で制限されるルールも同様です。
章立ての構造化
最終的に、主題文の制約は、章立てによって文書全体にまで展開されます。
これにより、文書全体の要素が、主題文を通して構造化されます。
読者は、見出しと主題文から必要な情報だけをピックアップできます。
文例
ここで、構造化された文書と、作文風の起承転結で書かれた文章を、私のつたない文章で書いてみます。
例文での説明対象は、以前の記事で書いた自作の「犬用おやつあげ＆ゴハンあげ機」です。
テクニカルライティング風の構成
まずはテクニカルライティング風の構造化した文章でまとめてみます。
【主題-全体】この装置にはゴハンあげ機能とおやつあげ機能があります。
【主題-1】ゴハンあげ機能を使うと、決まった時間にドッグフードを自動的に給餌できます。【補足-1-1(準備)】フードは、装置の端にある大型の皿の上に一食分を乗せます。【補足-1-2(タイミング＆量)】設定した時刻になると、一食分の全量が犬のもとに届きます。【補足-1-3】これにより、留守中にも給餌できます。
【主題-2】おやつあげ機能を使うと、遠隔操作でおやつを犬の元に届けることができます。【補足-2-1(準備)】おやつはベルトコンベア状の皿の上に、少量ずつ乗せます。【補足-2-2(タイミング&量)】スマホの「おやつ」ボタンで、１皿分のおやつが犬のもとに届きます。
全体はゴハンあげ機能とおやつあげ機能の2つの段落で構成されています。
２つの段落の要約は【主題文-全体】としてまとめられています。
各段落は、2つの機能の詳細情報として記述されていると同時に、それぞれの機能に特化した主題文と補足文で構成されています。
このような構成にすると、段落の独立性が向上し、冒頭の主題文だけで読み飛ばしの判断ができます。
作文風の構成
同じ内容を作文風の起承転結で書くと、次のような感じになりそうです。
【起】この装置は犬にドッグフードをあげる機能を持っています。
【承】設定ファイルで指定したゴハンの時間に、自動的に一食分のフードを給餌できます。装置の端にある大型の皿にフードを乗せておくと、全量が犬の元に届きます。
【転】また、少量のおやつをあげる機能も持っています。スマホの「おやつ」ボタンで、ベルトコンベア状の皿に置いたフードが１皿分、犬のもとに届きます。
【結】このように、留守中の指定時刻にゴハンをあげたり、遠隔操作でおやつをあげたりできるなど、機能の使い分けができます。
作文風のほうが全体が見えないまま、新しいトピックが次々と出てくる展開で、おもしろさがあります。
その反面、文書全部を咀嚼しないと、情報を取りこぼしてしまう不安を感じます。また、このような構成だと、後から情報を探すのは大変そうです。
これら２つの文例のどちらが良いかは目的次第です。
エッセイのような文章がテクニカルライティング風に書かれていてはおもしろくないですし、説明書や報告書が作文風に書かれていては大変です。
使い分けこそが最大のポイントです。
構造化による情報の整理
文章を構造化すると、情報が整理できる副作用が生まれます。
先ほどの文例は、本質的には次の表の情報を表しています。
このように情報をラベル付けすると、情報の抜けに気づくことがあります。
先ほどの文例では、【補足-1-3】の「留守中の給餌」が浮いています。
意味を考えると、これは「目的」の説明だとわかります。
そこで、おやつあげ機能に「留守中に犬と遊ぶことができます」を追加すると、各機能の役割がより明確になります。
こうした表だけを書いた仕様書をよく見かえますが、私は過度の省略を避けています。
行間の解釈を読者に押しつけると、誤った仕様伝達や背景の理解不足が発生し、トラブルの元になります。
最後に
技術文書を作成する際には、構造以外にも「てにをは」の使い方や主語述語の対応なども重要ですが、理解のしやすさや読み飛ばしの可否まで考えると、構造化が本質であるように感じています。
その一方で、技術文書では、何を記述するかという点も見逃せないと思っています。
様々なソフトウェアのヘルプは、文章のプロが書いていますが、ヘルプ画面を開いてしまったときには、激しい残念感を感じます。
これはなぜか……。
こうした技術文書の存在価値についての私なりの分析は、機会があれば別の記事にしたいと思います。