目的に応じた技術文書を書く
−共通基礎を応用形に結びつける−
|
一口に「技術文書」と言っても、目的や読者対象さらにはページ規模によって書き方・作り方がさまざまです。しかし、数ページの報告書も100ページ規模の製品解説も共通の基礎に立つ応用形です。基礎を応用につなげるのは、技術者の皆さんが得意とする手法です。
|
「誰に何を伝えるのか」を確認する
「要点が明確かつ具体的」であることが、技術文書の共通要件です。さらに、「読者に伝えるべき事項で構成する」ことが、それぞれの文書に求められる要件です。「読者に伝えるべき事項」が明確になれば、おのずと「読者に伝わる文体」が導かれます。基調となる文体が定まれば、執筆者にとって書きやすくなり、読者にとっては読みやすくなります。
文書の種類 |
文書の主たる目的 |
執筆者と読者の関係 |
報告書 |
知見の記録と知見に基づく論述・見解 |
報告者と報告を受ける側 |
機能仕様書 |
目的の共有と要件の取り決め |
目的を共有する開発者同士 |
議事録 |
決定事項の周知 |
会議の関係者同士 |
エンドユーザ向け製品解説およびマニュアル |
製品の知識と使い方の提供 |
メーカ(提供者)とユーザ(一般消費者) |
プログラマ向け仕様書 |
メーカ(提供者)とユーザ(プログラマ) |
「技術文書の共通基礎」と「文書の目的によって異なるポイント」は表裏一体です。たとえ特定の技術文書しか書かないとしても、さまざまな技術文書の共通点と相違点を知っておけば、どのような書き方をすればよいのかが明確になります。
-
しばしば、結論に至っても「・・・と思われる。したがって、・・・と考えられる」と、何が明らかで何が未確認なのかが曖昧な技術報告書に遭遇します。報告者として見解を明確に伝えたければ、「・・・と考える」あるいは「・・・と特定する」、「・・・推察する」などと正当な根拠に基づく明確な主張を示す文体を基調にするのが適切です。
-
また、機能仕様書の文体が混じったマニュアルを見かけます。同じ製品を対象にしていても機能仕様書とマニュアルでは目的も読者も異なります。マニュアルならば、読者(ユーザ)の視点で表さなくてはなりません。
ページ規模に応じた見出し階層で構成する
技術文書によっては、1ページの場合もあれば数百ページに及ぶ場合もあります。いずれの場合も、見出しで構成される点では共通です。ページ数が少ない技術文書では、見出しの数が少なく、見出しの階層化も最小限にとどめます。ページ数が多い技術文書では、見出しの数が増え、3階層ないし4階層で構成するのが通例です。
基本の応用形としてページ数が少ない文書や多い文書があります。基本が共通だからこそ、一貫性がある書式で技術文書を構成することができ、誰にとってもわかりやすい構成の文書になります。見出し構成の基本を把握せずに文書を作成すると、読者に受け入れられない“独りよがり”の書式に陥るおそれがあります。部門内では通じても、他部門さらには社外では通用しません。
-
技術報告書といっても、「試験報告書」、「障害報告書」、「成果報告書」、「調査報告書」など目的も違えばページ数もさまざまです。同じ見出し構成で定型化しようとすると、当然無理をきたします。無理な定型化は書きづらさの原因になるばかりか重要事項が的確に記載されない原因にもなります。
-
見出し構成の考え方を身につけておけば、文書の目的に応じた見出しを考案したり、定型文書の中に無理なく見出しを追加することができます。
「伝えるべき事項」で見出しを構成する
「誰に何を伝えるか」を確認したら、これを表題と見出し構成に反映します。表題は文書全体の主題であり、見出し構成は文書の骨格です。
見出しの「最上位となる階層(章見出し)」は、定型の見出しを用いるか、案件に応じて定型に一部変更を加えた構成にします。章見出しの中でいくつかの主題をさらに示す必要があるならば、下位の見出し(節見出し)を追加します。
大切なのは、見出し構成を決めるだけでなく、「各見出しで何を伝えるのか」を確認することです。方針を明確にしないまま文を書き始めてしまうと、すぐに行き詰まってしまいます。無理をして書いたとしても「何を伝えようとしているのか」が不明確な文書になってしまいます。
-
製品の開発になぞらえれば、見出し構成の検討は基本設計(製品の構想)に相当します。設計図の作成ほど綿密にする必要はありませんが、書き始める前に「文書の完成形」を想像しておくことは重要です。
-
既存文書の見出し構成の流用は、開発で言う「流用設計」に相当します。しかし、流用に頼りすぎると、個別の課題に対応できません。一方で、個別に見出し構成を考えるのも大変です。開発でも「流用設計」と「個別設計」を適宜に組み合わせるように、文書でも定型を基盤にした準定型の見出し構成を薦めます。
次ページに進む(ボタンをクリックしてください)
-
|
|
テクニカルライティングセミナー(出張開催形式)「技術の1stステップ」、「(同)+技術メール編」、「(同)+ビジネス文書編」では、要点が明確な技術文書を作成するための共通基礎と手法を事例中心で解説します。 |
|
|
.
|
|
|
|
|
|
|
|
|
|
|
|
.
|
-
技術文書の書き方−テクニカルライティングセミナー わかりやすい技術文書の作成手法−
Copyright: Takaaki-YAMANOUCHI/1995-2017
山之内孝明/有限会社 山之内総合研究所
Takaaki Yamanouchi/ Yamanouchi Research Institute, Ltd.