山修の開発文書品質入門(1) ―― 分かりやすい文章を書くコツ

山修の開発文書品質入門(1) ―― 分かりやすい文章を書くコツ

カテゴリ : 
基礎知識
 2011-11-4 10:00

 

山本 修一郎

開発文書では,「分からないものを書く方が悪い」という姿勢が大切です [1].後続工程の開発者が先行工程の開発文書を読んでも分からなかったら,自分の想像によって補うことになります.これでは,後続工程で先行工程の活動をやり直すことになってしまいます.

■短文を書く

分かりやすい文章の第1条件は,文が短いことです.文が長くなればなるほど,分かりにくくなります.
日本語の短文に含まれる平均文字数の目標は約50字だそうです [1].試しに,NPO法人 組込みソフトウェア管理者・技術者育成研究会(SESSAME)がサンプルとして提供している要求仕様書「話題沸騰ポット」の要求文に含まれる平均文字数を数えてみると,約26字でした.この要求仕様書は,短文性が高いと言えます.

■表現を統一する

文が短くても,開発文書に含まれる表現が多様だと分かりにくくなることがあります.
  「表現」と「意味」という関係から構文をとらえると,「異なる表現が同じ意味を持つ場合(表現の揺れ)」と,「同じ表現が異なる意味を持つ場合(意味の揺れ)」があります.どちらも,文書を理解する上で,問題があると思います.分かりやすい文章を作成するためには,表現の揺れと意味の揺れを減らす必要があります.

表現の揺れと意味の揺れは,「用語」と「構文を構成する要素」の両方に対して発生します.用語に対する揺れは,用語集を作成することにより解消できます.以下では,構文を構成する要素 に対する揺れについて説明します.

■複数の意味をもつ助詞はできるだけ使わない

「で」と「は」という助詞には,複数の意味があります.「で」には,「手段」と「状態」,「場所」を示す場合があります.「は」には,「主語」と「対象範囲」を示す場合があります.複数の意味を持つ助詞は,書く方からすれば使い勝手が良いものです.しかし,どの意味なのかを読み手が判読する必要があるため,理解しにくい面があります.このため,「で」と「は」をできるだけ使わないようにすることにより,分かりやすい文になります.

■「ことで」or「ことにより」

手段や目的,関係を表現するためには,「ことで」,「ことにより」,「によって」,「して」,「たら」,「と」などが用いられます.開発文書では,あえて異なる助詞を使い分ける必要があるとは思えないので,統一することが望ましいでしょう.

例えば,先ほど例に挙げた話題沸騰ポットの要求仕様書の記述[2]では,18個の要求文の中に8個の手段記述があるのですが,この8文の中で6種類の手段表現が使われています.もし手段表現を「により」に統一すれば,使用単語数を削減できます.

■「ときは」or「場合は」

システムや対象物の状態を表現するためには,「に」,「で」,「たら」,「ときは」,「場合は」,「ならば」などが用いられます.状態表現を統一することにより,使用単語数を削減できます.

■「する」or「させる」or「を行う」

機能表現にも揺れが発生します.話題沸騰ポットの記述[2]では,次の8種類の表現が出現します.①「~を~する」,②「~できる」,③「~させる」,④「~をする」,⑤「~をさせる」,⑥「~を行う」,⑦「~機能を付ける」,⑧「~しない」.

さらに,それぞれの機能表現が2~3回ずつしか使われていません.これらを1つの機能表現に統一することにより,文書作成だけでなく文書理解も容易にできます.

■改善のためには測定が有効

分かりやすい文章を書くためには,文を短くすることと,表現の揺れや意味の揺れを減らすことが重要であると述べました.試しに,開発文書に含まれる単文の文字数を測定してみてください. また,単語の出現頻度と意味種別を測定してみてください.実際に,自分たちが作成している開発文書を測定し,見直してみることにより,短文性が向上し,表記揺れを減らすことができます.

なお今回は,構文を構成する要素についても,単語間の関係やパラグラフ内の論理構造,パラグラフ間の関係などについては触れませんでした.これらについては,次回以降,考察していく予定です.

 

参考文献


[1] 下村耕平,これからの技術文書,国際化時代の技術者・翻訳者必携,競争に勝つドキュメンテーションの論理と方法論,アルカ,1987
[2] 組込みシステム教育教材 話題沸騰ポット GOMA-1015型 要求仕様書,http://www.sessame.jp/workinggroup/Wo ... up2/POT_Specification.htm

  • コメント (0)
  • トラックバック (0)
  • 閲覧 (6583)

トラックバック

トラックバックpingアドレス https://asdoq.jp/blog/tb.php/4

サイト内検索

カテゴリ一覧

ログイン

ユーザ名:

パスワード:

次回からIDの入力を省略



パスワード紛失