技術文書の書き方

H11.6.28 米倉

 

.はじめに

 

近年の情報化社会において、正確な情報をできるだけ迅速に相手に伝えることの価値はこれまでにも増して重要視されている。当然のことながら情報の担い手は最終的には人間であり、機械ではない。従って森羅万象の観測結果や収集したデータの分析結果から正確な情報を抽出する責任とそれを相手に正しく理解されるように、そして理解しやすいように提示する責任はあくまでも人間一人々々にあることは言うまでもない。コンピュータではデータを変換・集約することはできても、情報を解釈することはできないのである。そう考えれば、集約されたデータをいかに相手にうまく伝えるかは、情報化社会における重要課題となろうことは容易に予想される。そこで文書の書き方を学ぶ必要がうまれてくる。

そのような状況の下、本稿では、理工系大学のカリキュラムを習得するうえで不可欠な技術文書の書き方について説明する。本稿で対象とする読者は本学工学部の2,3年次学生を想定している。従って、各種の授業・演習・実習・実験科目などレポート、報告書を課される科目は相当数あろう。そこで、採点者にすこしでも自分の主張を理解してもらうため、あるいは好印象を与えるため、ひいてはレポートの評価につなげるためにどうすればいいか?は読者の最も重要な関心事のひとつとなろう。これらは社会においてはさらに重要性を増す。本稿の読者の大多数は、いったん企業に入社すれば研修報告書、種々の客先説明書、予算要求書、予算立案書、調査報告書、仕様書、設計書、社内(外)論文、新入社員研修向テキストなど、ほぼ一年中技術文書作成に追い回されることになる(とあえて断言しよう)。それらで好評価を受けることの重要性は大学のレポートの比ではない。

本稿ではそういった技術文書の作成についての基本的な技法、あるいはノウハウをまとめてみる。そこでまず、一般論としてどのような手順で文章化していくか、すなわち文章化の心構えを次章で述べる。続く第3章では情報を上手に提示する順序と文書全体の構成方法を述べると同時に身近なケーススタディを行い、最後に第4章では個々の文を書く際の確認すべきキーポイントを示していく。

 

.文章化の心構え

 

.1読み手は人間である

技術文書に限らず、いかなる文章を書く場合においても最も重要なことは、それを誰かが読む必要があるということを熟知すべきという点であろう。誰かが読む以上、読む人が読み易いものであること、理解し易いものであること、楽しく飽きずに読めるものであることに関心を抱くのは当然である。そこで具体的には、

  1. どうしたら読み易いか?
  2. どうしたら理解し易いか?
  3. どうしたら飽きないものとなるか?

を考えることになる。このように考えると、結局は誰が読むのかを知ることが文章化の第1歩であることに気づく。簡単に言えば特定読者を仮定する場合と不特定読者を仮定する場合である。本稿の読者は工学部の学生である。趣味でエッセイや詩や小説などを書く場合を除けば、レポート、プログラムマニュアルなど、ほとんどが特定読者を仮定できる(因みに本稿の読者も工学部2,3年次学生という特定をしている)。そこで次に考えるべきことは、特定される読者すなわちターゲット層の性質を知る、言い換えれば読み手の視点に立つということになる。それにより説明の範囲を拡大・縮小することは言うに及ばず、使用する用語も選ばなければならない。授業の課題レポートであれば読者はその科目の担当教職員であり、技術用語を用いた正確で簡潔な文書を要求されるし、プログラムマニュアルの場合読者はそのプログラムの利用者であるので、初心者向けの平易で分かりやすい文書を要求される。両者の場合明らかに「相手」は異なる。これらターゲットの性質による文書の書き方の相違点をまとめてみれば、

  1. 読み手の予備知識の仮定
  2.  一般的には読み手の目的、年齢、分野、経験などによる予備知識の違いを考慮せよ、ということになるが、ここではもっと狭い意味で、読者に応じて使用する技術用語を使い分けるということである。専門家向けの技術用語を使うということはその周辺の説明が不要となることを意味する。逆に初心者向けの平易な文書を書こうと思えば専門用語をいきなり出すのでなくその用語の説明が必要となり文章は一般に長くなる。また類似した専門用語がある場合は、専門家向けの文書であっても一通り「要約」程度は付けるべきである。「計算機科学」と「計算幾何学」はその良い例であろう。また、自分たちだけに通用する「流行り言葉」や「省略言葉」なども技術文書には不適格な場合が多い。よほど読者が限定された文書でなければ、「ドライバ」だけでは「運転手」なのか「コンピュータの入出力ドライバソフトウェア」なのかそれとも「ねじ回し」なのか分からない。この場合でも読み手が文脈から判断することは可能であるが、それを期待した文書を書くべきではない。

  3. 読み手に伝えたい内容と簡潔性
  4. 何を伝えたいか?あるいは読み手がどんな情報を求めているかを十分に考慮すべきである。簡単には、読み手になるであろう人々の顔を思い浮かべること。そしてその人達が知りたがっているであろう内容に的を絞って書くことが重要である。時間的制約のある読み手に対して無駄な事柄で「お茶を濁す」ような技術文書は不快感以外の何物をも与えない。これは学生のレポートに時々見られる例である。

    また簡潔な文書は、読み手に多義的解釈や理解のための無駄な労力を与えない。その意味で文章は簡潔であるほど良いといえる。複文の多用などで一つの文にたくさんの意味を込めようとすればするほど内容がわかりにくくなるのはこのためである。その意味で一文一義(一つの文に一つの意味)を心がけることが重要である。「プログラムAはプログラムBと同様に高速ではなかった。」は一見簡潔な一文のように見えるがそれは、@プログラムBは高速だがプログラムAは高速ではなかった。AプログラムBもプログラムAも高速だが、ABほどではなかった。BプログラムBは高速だが、プログラムAは高速ではなかった。の3種類の解釈を持つ(何故かを考えよ!)。これは否定形により生まれた多義的解釈の例である。一文一義ではできるだけ肯定形を使うことが望ましい。「プログラムBAと比較してやや高速であった。」などとすれば良い。

  5. 読み手に応じたメディアの効果
  6. 文書を読んだ読み手が勝手に抱いてしまうような誤解、曲解、妄想の類を持たせないようにすることは書き手の責任である。技術文書は必ず一つの意味を読み手に与える。そのための方策として図、グラフ、表、イラスト、あるいは画像などを適切に配置することは重要である(ハイパーテキストでは音声やアニメーション、動画像までも配置することができる)。しかしながらこの方法も読み手に応じて加減する必要がある。数多く図を付ければ説明は不要と思ったり、例示によって全貌を類推させようとすることは危険である。一般的には読み手をその分野の専門家に限定するほど余分な図示の必要は減り、初心者を対象とするほど図示の必要が増す(といっても文章が不要になるわけではない)。

    なお、表を掲載する場合そのタイトル(例:表2.プログラム別実行時間の内訳)は表の最上段に、それ以外のメディア(図、グラフ、イラスト、画像など)を掲載する場合のタイトル(例:図4.CPUクロック向上とそれによる発熱)は最下段に配置する。また、数式は行末に式番号を配置し、式番号で引用する。

  7. トップダウン手順>ボトムアップ手順

一般に、情報は「周知の事柄、一般通念」から始めて「価値ある結果」に結ぶことが重要である。「一般的概念」から「具体的結論」と言い換えても良い。このような順序をトップダウン(top-down)手順と呼ぶことにする。これに対して、いくつかの例や個別の知見を並べそれらを貫く一般的で高次な結論を導いていく結び方をボトムアップ(bottom-up)手順と呼ぼう。

一例: A(xxちゃんてyyじゃないの?)

B(うん。俺もそう思う。そう言えばzz君もyyだよね!)

A(そっか!じゃwwな人ってみんなyyなんだー)

B(納得!)

 という会話はボトムアップ手順で結論?を見つけた例であろう。それなら後者の方が圧倒的に分かりやすいと思う読者は多いかも知れない。しかしながらこの手順の不利な点は読み手に書き手と同じ感覚・理解を強要する点であり、この感覚を持たない人を無視して結論付ける点である。また、ともすればこの感覚・理解の強要は独断と偏見を生み出しかねない(少なくともそういう警戒感を与える)。逆にトップダウン手順では書き手の側にそのような強要を排除しなくてはならないという心の準備が必要となり、その結果、論旨の明確さと読みやすさがうまれる。その意味で技術文書は可能な限りトップダウン手順に従うべきであろう。ただし、例外として読み手がかなり限定され、なおかつ書き手と読み手の間で共通の感覚・理解が十分に仮定できる場合などではボトムアップ手順を使用しても良い。

.2 ストーリー展開の手順を身につける

ここでは前述したトップダウン手順を詳細化してみよう。「周知の事実、一般通念」から始めて「価値ある結果」に結ぶためにはどうすれば良いか。これを突き詰めれば、以下の手順例に要約される。

手順例

  1. 現状・背景の確認
  2. 現状の課題による動機付け
  3. テーマやねらいの絞り込み・目標の設定
  4. 設計と実装(データ収集の過程)
  5. 評価(データ集約)
  6. 評価や集約結果からの結論の導出
  7. 目標の達成度
  8. 達成し得なかった課題・新たに発生した課題

文章化の際にはそれを書くに至った動機を正確に知ることが重要である。それにはまず、上記の手順(1)で現状や社会的背景を正しく認識し、(2)それにより表面化した課題や問題点を挙げてみることが重要である。課題が与えられている場合の実験・演習レポートにおける動機付けとは、そのレポート課題の達成により、これまで明らかでなかったどういうことが明らかとなり、次に続くいかなる応用課題に対処できるようになるかを意味する。

続く(3)ではテーマをどのように絞り込むか、どういう観点から掘り下げるかという点と

どの程度の目標に設定するかという点を決める。プログラムの改良というテーマを例にとれば、達成したいのはアルゴリズムの簡略化なのか、機能の拡張なのか、実行速度の向上なのか等と、どの程度の簡略化、拡張、高速化を目標とするかである。実験・演習レポートの場合は与えられたテーマの最終目標を正確に述べることになる。

更に(4)では目標設定(3)によって設定した目標をどのように達成するか、すなわち目標達成の手法に的を絞る。開発や構築といったテーマの場合は目標達成のためにどのような設計・実装を行うのか、ならびにその合理性を述べ、調査をテーマにする場合はどのようにデータを収集するかすなわちデータ収集のプロセスとその合目的性について述べることになる。

手順(5)ではこれまでの手順で得られた実装結果やデータから、その評価や情報集約を行う。具体的には、実装した結果システムの機能や効率がどのように実現・拡充したのか、またデータを集約した結果の可視化(適切な表やグラフが用いられる)により何が言えるのかを述べるのである。この手順が正しく行えるか否かによって意図した技術文書の完成度がほぼ決定される。

 続く(6)で、結果された評価や情報集約から結論の導出を行い、手順(7)では手順(3)で設定した目標をどの程度達成できたか、新たな知見は何かを述べる。それにより、達成できなかった部分がどの程度残り、その場合の反省点、新たに得られた課題などを手順(8)に述べて全体を結ぶ。このような手順により、簡潔でまとまりのあるストーリーが形成されていく。これらはまた報告書の作成を義務付けられている場合の調査、分析、開発、検討などの作業の際に計画すべき報告材料のリスト(何を報告しなければならないか)と言い換えても良い。

 

.文章の構成方法

 

.1情報提示の順序

ここでは情報を提示する順序について整理してみる。

一般に文書の読み手はその内容が自分に関心のあるものかどうか、読む必要があるものかどうかをまず判断したがる。そのためまず見出し・題目に目を通し、次に要約部分を読む。ほとんどの読み手はこの時点で内容の自分に対する重要度・関心度を判断し、それが高いと判断したものは本文に読み進むがそれが低いものをそれ以上は読まない。技術文書はこのような読み手の性質を利用する必要性から、以下の順序で情報を提示している。

  1. 見出し・題目 (情報が凝縮されたキーワード、目を引くためのもの)
  2. リード・要約 (5W1Hの必要最小限部分)
  3. 本文     (5WHの詳細な説明)

新聞や雑誌の記事では必ず5W1Hの原則が守られているのに気づく。5WHとは、誰が、いつ、どこで、何を、なぜ、どのように、のキーワードである。「昨夜10時ごろ、都内足立区に住むAさんが自宅近くの路上でバイクに乗った2人組みに突然手提げバッグを奪われた。警察では通り掛かりの犯行とみて2人の行方を追っているが2人は依然逃走中。」新聞のリード部分によく見られるこの種のものは5W1Hが盛り込まれた簡潔な文章である。技術文書においては要約、アブストラクトにあたる。必要不可欠な事柄のみを抜粋してその他を切り落とした結果、読み手に与える読解の労力を最小限に押さえている。また、読み手の読解を助けるもう一つの手段として、箇条書きの利用がある。箇条書きは実はこのリードと同じ役割を果たしている。箇条書きは、特に詳細な内容を簡略化したキーワードで表すという方法によって読み手の関心度を高めるものである。

新聞や雑誌の記事におけるリード部、技術文書における要約部分を読んだ読み手が、更に詳細な内容を知りたい場合のために本文が必要となる。本文では5W1Hについての詳細な情報が含まれると同時に、これら5W1Hに関する書き手側の(事実を基にした)予測や推測他などが盛り込まれることもある。

見出し>リード>本文という情報提示の順序は、実は人が情報を視覚により処理しやすい順序となっている。

.2文章の組み立て方

前節により、簡潔で凝縮されたものを先に提示し、詳細で豊富な情報を後回しにすることが一般的であることが知られた。それでは、2章で述べたストーリーの手順と前節の内容を踏まえて文章全体の組み立て方を考えよう。すなわち、文章全体のストーリーは2章の手順(1)〜(8)に従いつつ、大枠あるいは各部分ごとには(見出し>リード>本文)による提示順序に従う組み立て方である。読み易い技術文書にはこれらの原則が埋め込まれている。

以下にこれらの見本となる一例を示す。

 

ハイテク機器の視聴ガイド

 

大西 晋也 皆川 洋喜

名古屋大学工学部情報工学科、名古屋市

 

あらまし 人間の視覚と聴覚の特性を生かした機器操作ガイドを提案する。視覚ガイドによりユーザの注意を適切な場所へ誘導し、聴覚ガイドで、言語的に操作の方法を捕捉する。ガイド付き機器を試作し、評価実験を行ったところ、従来の方法より高い評価を得た。

キーワード 視覚、聴覚、ヒューマンインタフェース、電子マニュアル、対話モデル

 

1.まえがき

我々の身の回りには多くのハイテク機器が存在する。家庭ではビデオ、オーディオ機器、エアコンなど、オフィスではコピー、コンピュータ、ファックスなど、工場ではマニュピュレータなどである。これらのハイテク機器はマイクロコンピュータを内臓し、多機能で、多くの場合複雑な操作を必要とする。

これらの操作のすべてをマスターすることは非常に困難である。特に使用頻度の低い操作は覚えることができず、マニュアルを参照することが不可欠である。..中略...

Macintoshのバルーンヘルプなどでは、マウスカーソルが指すボタンなどの説明をさせることができるが、機器そのものにこのような機能が内臓されたものはない。

そこで、我々はハイテク機器の視聴覚ガイドを提案し、試作した視聴ガイド付きのコピー機により行った予備的な心理実験の結果を報告する。

2.視聴ガイド

従来型機器の問題と、提案する視聴ガイドを、コピー機を例にして説明する。

  1. 従来型機器 操作不明のとき、ボタン機能が不明のとき、トラブル発生時などにはマニュアルを調べる。そこで印刷されたマニュアルというものが存在する。しかし、このマニュアルには2つの問題がある。

  1. マニュアルの紛失
  2. マニュアルを調べるのは大変

......中略 ......

  1. 視聴ガイド 一般に機器には多くのボタン、スイッチがある。これらのボタンにはシンボルやアイコンが書かれている。

3.実験

現在のコピー機を改良して、視聴ガイド付き機器を製作し、評価実験を行った。

    1. 試作した視聴ガイド付きコピー機

(コピー機:リコピーFT3060 デスクトップタイプのコピー機である。(中略)

3.2 実験の方法

(課題) コピー機を使っている最中に紙がつまった状態を想定し、被験者につまった紙を取り除いてもらう。

(操作方法) 以下の3つの方法で操作してもらう。

  1. 提案方法:視覚によるガイドと聴覚によるガイドをともに使う。
  2. 従来方法:従来のマニュアルのみを使う。
  3. 参考方法:提案方法との比較のため、(中略)

(被験者)...........(中略)....

(評価方法)..........(中略).......

3.3 結果

(提案方法)........(中略)......

(従来方法)........(中略)......

(参考方法)........(中略).....

3.4 考察

・提案方法(評価の平均4.3)は、従来方法(同2.3)より高い評価を得た。

視聴による操作ガイドを用いた実験では、音声を聞き、視聴覚ガイドが...(中略)..

4.むすび

人間の視覚と聴覚の特性を生かした視覚・聴覚的なガイド機能をもつ機器を提案し、評価実験を行った。視覚、聴覚の役割の分担、人と機器とのインタラクションの方法などを更に詳細に検討することが今後の課題である。

文献

  1. 黒須正明 “ヒューマンインタフェースのデザイン”、情報処理、vol.34,no.8,pp.1063-1072,1993.

 

図1.情報提示順序とストーリー手順の上手な例

 

ここでは、あらましが本文全体のリード部の役割を果たしている。あらましでは短く3つの文章(一文一義)で、「…を提案する。…を捕捉する。…高い評価を得た。」と締めている。読み手はこの3つの文章だけで事の重要性を判断しきれる。あらましを読んで、より詳細な内容に関心を持つに至った読み手は次に第1節「1.まえがき」に目を転じる。そこでもやはり、背景、現状の問題点を簡潔に述べた後、「そこで、」と著者らが設定した目標と結果を、本論のリードとして述べている。

第2節では「2.視聴ガイド」と題し、従来の問題と筆者らの提案により何がどう改善されるかをより詳細にのべている。ここでは箇条書きを多用し、“従来”と“提案”の対比を強調している。第3節では提案方法がどの程度有効か、「3.実験」による評価を試みている。ここでは、より細かい小節に分けて、順に「試作の説明」「実験の方法」「(実験)結果」「考察」として論旨の明確さと読みやすさに配慮している。ここでも本稿2章で述べたトップダウン手順をみることができる。

最後に第4節では「4.むすび」と題してこの論文で行った結果を端的にまとめつつ、残された課題についてもキーワード化して触れている。無駄のない読みやすい文章といえよう。

さて、これを参考に文書を類型化してみると、以下に示すような目次の例が生まれる。

  1. 題目
  2. 概要(文章全体のリード部+キーワード)
  3. 1.まえがき(現状の確認+問題・課題による動機付け+目標設定+本論構成のリード部
  4. 2.本論の前半(事前知識の確認+設計・実装・調査のプロセス)
  5. 3.本論の後半(評価・情報集約+考察・それらからの結論の導出)
  6. 4.あとがき(目標の達成度+反省点+以降に残した課題)
  7. 参考文献(文章内で引用した文献や図書、資料の列挙:著者、資料名、出版元、年号を書く)

 

図2. 目次構成と情報提示の一例

読者はこの例を参考にレポートの目次を作成されると良い(個々の場合に応じて変更の必要が生まれることは言うまでもない)。

3.3 ケーススタディ

  1. プログラミング演習レポートの場合
  2. プログラミング演習レポートの場合、演習課題は与えられている。そこで、第1章(まえがき、問題提起)として個々の課題のもつ意味とその課題の達成により得られる新たなノウハウや知見を最初に述べる必要がある。また、ここで課題に対するパフォーマンス等の数値目標を自ら設定したりするのも良い。

    続く第2章(問題解決手順、問題解決の考え方)では、与えられた課題をどのように解決していくのか、すなわちアルゴリズム設計方針などを記し、その正当性や効率についても触れると良い。これはプログラムの機能仕様書という性格を含む。次にプログラムの内部仕様として、プログラムの制御構造ならびにデータ構造、そしてプログラムの外部とのインタフェースなどを詳細に(図、チャート等を用いて)説明すると良い。

    第3章(評価、実行結果)では実際にプログラムを動作させた結果(正規の手順ならびに誤った手順など)を詳細に述べる。実行速度について議論する場合はプログラム内の各ロジック毎の実行時間を個別に計測し、どのロジックでどれだけの時間が経過しているかを表などを用いて詳細に論じること。

    第4章(あとがき、考察)ではこの課題をどの程度達成できたか、反省点は何か、更なる課題として何を考察しなければならないかなどを議論する。最後に参考文献、ならびに付録としてプログラムリストを添付する。

  3. 実験・実習レポートの場合

実験レポートの場合においても課題は与えられている。そこで、第1章(まえがき、実験の目的)では、何の測定とどのような原理によって何を説明しようとしているのかを簡単に記す。 手引の Dead Copy ではなく、 自分の言葉で書くことが望ましい。

次に第2章(実験経過)では実験の作業行程、実験で得られたデータなどを書く。つまり、

o 実験手順は、必ず自分が実際に行なったことをありのままに報告すること。 このためには、経過をその場で記録しながら実験を進めることが必須となる。

o レポートは、 それを読むだけで後になっても実験内容や結果が確認できるようになっていなければならない。よって、「テキストに書かれている通りに作業した」、「詳細はテキストを参照のこと」 といった記述があってはいけない。

o ナマの数値を表 (Table) の形で記す。また、グラフなどを用いてデータを可視化する。

技術文書では図表が統一された形式で記述されることも重要である。そこで、

o 図説 (図のタイトル) は図の下に、 表題 (表のタイトル) は表の上につける。また、図表については、本文中で必ず説明する。

o グラフを書く際には、 物理量、 単位、 目盛の記入を忘れないこと。

そして第3章(考察・評価)で実験結果が正常であるかどうか、理論値と異なった場合にはその理由の推測、実験結果から導き出される事実、予想などを客観的に書く。

そして最後に第4章で与えられた課題の結果と、実験の結果得られた知見をまとめる。

 

4.まとめ

 

本稿では、本学工学部2,3年生を対象として技術文書作成に関する基本的事項、ノウハウについて述べてきた。このように見れば、技術文書の書き方は小説やエッセイなど文学作品のそれに比べて極めて規則化されていることが知られよう。読者諸君はこれから書くことになるであろう実験・演習レポート、卒業論文、修士論文ならびに企業入社後に経験する種々の技術文書の作成に是非役立てて頂きたい。なお、本稿を結ぶにあたり、個々の文章作成に際して忘れてならない3つの原則を再度確認しておく。

 (1)読みやすさ

 各章、各節に何を書けば読みやすいかを考えながら(3章の目次構成例を参考に)目次を先に作ること。この時点で(内容が補えないなどの理由で)書けない章や節があればそれは調査する対象として後に回し、書ける部分から書くのがよい。また、2、3章で述べたように図、イラスト、画像、表、グラフなどを適切に配置したりすることで、読み手の理解を助ける努力をすること。

(2)正確さ

書き手は正確に書こうとすることで、自分自身の正確な理解の確認ができる。日本語では形容詞(形容詞節)、副詞(副詞節)の配置のしかたによって種々の異なった解釈が生まれる。前章の論文例における第1節の第3文「これらのハイテク機器はマイクロコンピュータを内臓し、多機能で、多くの場合複雑な操作を必要とする。」は、「これらのハイテク機器は多くの場合マイクロコンピュータを内蔵し、多機能で、複雑な操作を必要とする。」となりがちであるが、筆者はあえて「複雑な操作が必要である」ことが多くの場合にあてはまるのであって、「マイクロコンピュータを内臓したり、」「多機能であったりする」のはそれら全てにあてはまることを主張しているのである。

解釈の正確さを確認したり、主張したい点がうまく表現できているかを確認するには形容詞節と副詞節がどこにかかっているかの関係を図にしてみるとよい。

 (3) 短さ

簡潔であることは読み手の理解を助ける。そのため、一文一義を貫くことが重要である。また、同義の文章を重複しないということも簡潔さにつながる。初心者の文章では「提案するハイテク機器の視聴覚ガイドは」という語句を何度も使用しがちである。これは大抵の場合くどく、読みにくく感じられる。2度目以降は単に「視聴覚ガイドは」という語句で十分であろう。

 

参考文献

  1. 高橋昭男 「技術系の文章作法」共立出版(1995)
  2. 末武国弘 「科学論文をどう書くか」講談社ブルーバックス(1981)

(3) 大西昇 他「ハイテク機器の視聴ガイド」電子情報通信学会論文誌、vol.J79-D-II, no.6,pp.1166-1168 (1996)