最新エントリー

 山本 修一郎

この連載コラム「山修の開発文書品質入門」では,開発文書に携わる皆さんに役立ちそうな開発文書の品質につながる知識を分かりやすく解説します.

バック・ナンバ

 

ソフトウェア開発における知識の流通形態として,文書化と対話を考えることができる.文書化を徹底すれば対話量を削減できる.逆に,文書量を削減すれば,必要な知識を獲得するために,多くの対話が必要になる.

アジャイル型開発では,文書化量は削減する代わりに,濃密な対話によって開発に必要な知識を補完することになる.

たとえば,アジャイル型開発では,「①プロセスとツール,②理解しやすい文書,③契約交渉,④計画順守」よりも,「個人と対話,動くソフトウェア,顧客連携,変化対応を優先すること」に価値をおいている[1].これによって,ソフトウェア開発のさまざまな無駄を省くことを目的としている.無駄な文書やコードを作らないことと,逐次的にソフトウェアをリリースして開発期間を短縮することなどの特徴がアジャイル型開発にはある.

これに対して,ウォータフォール型開発では,工程を明確に定めて工程生産物としての開発文書を作成する.曖昧さや抜け漏れのない開発文書を作成することにより,手戻りのない開発を目的としている.

以上の議論から,文書化量を横軸,対話量を縦軸として,アジャイル型とウォータフォール型の開発をプロットすると,図1のようになる.

 

図1 文書化と対話からみたアジャイル型とウォータフォール型の開発

アジャイル型開発を進めるためには,対話能力が開発者に要求される.しかし,現場の開発者は十分な対話能力を持っていないことも多い.そこで考えられるのが,対話能力不足を文書で補うことである.実際,ある研究会で筆者がこの図を紹介した際に,アジャイル開発の現場でウォータフォール型の手法が見直されているという話を聞いた.図1でいえば,曲線の中間に位置づけられるような開発手法が現場で求められているということであろう.

そのような中間的な手法として,エレン・ゴッテスディーナーとメアリー・ゴーマンによる発見から納品へ(Discovery to Delivery, D2D)がある.

D2Dでは,文書に基づいて対話を構造化する「構造化会話(Structured Conversation)」を提案している.D2D型開発を図1に付加すると,図2のようになる

 

図2 文書化と対話からみたD2D型の開発

D2Dでは,対話を構造化できるように適応した文書を提案している.すなわち,表1に示すように,D2Dでは,開発プロダクトの7側面に対して,対話で活用すべき文書を提示している.

 

表1 文書化と対話からみたD2D型の開発
側面(dimension) 説明 文書
ユーザ(user) プロダクトと相互作用する主体 ロールマップ,ペルソナ
インタフェース(interface) ユーザ,システム,デバイスとプロダクトとの接続関係 コンテクスト図
アクション(action) プロダクトがユーザに対して提供する能力 ビジネスプロセス図,シナリオ(Given-When-Then),機能マップ,依存性グラフ,バリューストリームマップ,ストーリーマップ,能力マップ,フィーチャ,ユースケース
データ(data) プロダクトが操作するデータと有用な情報 状態図,データモデル,データ辞書,用語集
制御(control) プロダクトが満たすべき制約 決定表,決定木
環境(environment) プロダクトが適応する物理的特性と技術基盤 場所,物理条件,構成,使用形態,技術基盤比較表
品質特性(quality attribute) プロダクトが持つ運用と開発の基準を示す特性 プランゲージ(Planguage),品質特性シナリオ

 ここで,プランゲージ(Planguage)[3]は品質特性を可視化するためにGilbが提案したテンプレート形式の表記法である.Baasらが提案した品質特性シナリオ[4]は,①発生源,②刺激,③環境,④シナリオ,⑤システム,⑥成果物,⑦応答,⑧評価基準を記述することによって,品質特性を明らかにできる.

 

参考文献

[1] アジャイルソフトウェア開発宣言, http://agilemanifesto.org/iso/ja/manifesto.html

[2] Ellen Gottesdiener, Mary Gorman, Discover To Deliver: agile product planning and analysis, EBG Consulting, Inc., 2012.
    (エレン・ゴッテスディーナー,メアリー・ゴーマン,発見から納品へ- アジャイルなプロダクトの計画策定と分析,株式会社オージス総研訳,ブックウェイ,2014.)

[3] Gilb, Thomas, Competitive Engineering: A Handbool for Systems Engineering, Requirements Engineering and Software Engineering Using Planguage, Butterworth-Heinemann, 2005.

[4] Baas, Len, Paul Clements, and Rick Kazman, Software Architecture in Practice, second edition, Addison-Wesley, 2003.
   (前田他訳,実践ソフトウェアアーキテクチャ, 日刊工業新聞社,2005.)

 

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

      山本 修一郎

 

この連載コラム「山修の開発文書品質入門」では,開発文書に携わる皆さんに役立ちそうな開発文書の品質につながる知識を分かりやすく解説します.

バック・ナンバ

 

ASDoQでは現在,システム開発文書品質とは何か、その品質特性にはどのようなものがあるかを定義する活動を進めています.

 

本稿では,システム開発文書の中でも,文書としてとくに大きな役割を担う要求文書の品質に関して,これまで研究されているものを紹介します.

前稿でも紹介した国際要求工学委員会(IREB)[1]は,要求文書に関連する教育単位(EU:Education Unit)を定めています.

その中の「要求の文書化(EU4)」には,教育目標として「要求文書の品質基準(EU4.5)」(要求文書の品質を活用できる)が設定されています.今回は,IREBが定義する「要求文書の品質基準」とはどのようなものかを,解説します.

 

 IREBは,要求文書が満たすべき品質基準として,IEEE std.830-1998 [3] が推奨する次の4項目を参照しています[1][2].

  • 明確性と一貫性
  • 修正容易性と拡張可能性
  • 完全性
  • 追跡性

さらに,要求文書は後続する開発工程の基礎となるので,要求文書が明確な構造をもつ必要があるとしています[4].

 

 以下に,それぞれの項目を説明します.

 

■  明確性と一貫性

要求文書が明確で一貫しているためには,個別の要求が明確で一貫していることが必要です.また,個別の要求が互いに矛盾していないことが必要です.

そのために,要求文書と要求に一意な識別子を付与しておきます.これによって,要求文書と要求との間を矛盾なく明確化できます.

ここで,「明確性」と「一貫性」とは,それぞれ次のように定義します.

【明確性】 要求が異なる複数の意味に解釈されないとき,この要求は明確である.

【一貫性】 異なる要求が互いに矛盾しないとき,これらの要求は一貫している.

 

 修正容易性と拡張可能性

プロジェクトの進行に従って,要求の変更・追加・削除が発生するので,要求文書が容易に拡張できるようになっている必要があります.したがって、要求文書の構造は修正、拡張が容易である必要があります.

 

■  完全性

要求文書が完全であるためには,次のことが必要です.

  •  適切な要求をすべて含んでおり,それらの要求が完全に文書化されていること
  • システムの機能について,すべての可能な入力や環境要因に基づいて必要な応答を記述すること
  • これらの記述には,入力や環境要因の逸脱に対する例外処理も含むこと
  • 応答時間や可用性,操作性などの品質要求についても記述すること

 

また,要求文書の様式面での完全性としては,次のことが必要です.

  •  図表および参考文献が番号付けられ,本文で適切に参照されていること
  • 重要な用語の定義が要求文書で記述されていること

 

■  追跡性

要求文書と、業務プロセスやテスト計画・設計書などの他の文書との関係に基づく追跡性があることは,要求文書の重要な品質基準です.

 

■  明確な構造

明確な構造を持つ要求文書では,必要な部分を選択して読むことができます.そのため可読性を向上できます.明確な構造の要求文書を作成するためには,たとえば,IEEE std.830-1998が推奨するソフトウェア要求仕様の標準的な構成例などが利用できます.

 

参考文献
[1] The home of Requirements Engineering, http://www.ireb.org/
[2] IREB Certified Professinal for Requirements Engineering - Foundation Level-Version 2.1 Dec.20th 2012
[3] IEEE Std 830-1998, IEEE Recommended Practice for Software Requirements Specifications, 1998
[4]  Klaus Pohl, Chris Rupp, Requirements Engineering Fundamentals, A Study Guide for the Certified Professional for Requirements Engineering Exam Fundamental level / IREB compliant, rockynook, 2011
 

 

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

  山本 修一郎

 

開発文書品質の研究というと耳新しく聞こえますが,開発文書の構文や構造,要求仕様テンプレートなど,研究の役に立ちそうな素材はこれまでに研究されてきた分野の中に転がっています.この連載コラム「山修の開発文書品質入門」では,開発文書に携わる皆さんに役立ちそうなそれらの知識を分かりやすく解説します.

バック・ナンバ

 

開発文書の作成のために,文書のテンプレートを用意している組織や開発チームもあるかと思います.ルールや形式を決めて,それに当てはまるように記述することは,読み手の解釈の範囲を限定しますから,複数の解釈を避けることにつながります.

本稿では,2つの国際標準機関が取り決めている要求文のテンプレートの例を紹介します.

 

■IREBが規定する要求文書化の項目

国際要求工学委員会(International Requirements Engineering Board, IREB)[1]が要求工学専門家を認定するための基礎レベルのシラバスを提供しています.このシラバスでは,要求文書に関連する教育単位(EU)として,次の項目を定義しています.

  • 要求文書化(EU4)
  • 自然言語による要求文書化(EU5)
  • モデルに基づく要求文書化(EU6)

 

とくに,「自然言語による要求文書化(EU5)」の基礎レベルのシラバスで述べられている要求テンプレートを解説します.

 

■要求の義務の強さを示すための要求テンプレート

要求の定式化における言語効果を削減するために,容易に学習でき適用できる方法が要求テンプレートです.高品質な要求を作成する上で,要求テンプレートが要求執筆者を効果的に支援します.IREBは,要求テンプレートによって要求を5段階に定式化しています.

  • 法的な義務を決定する
  • 要求の中核を決定する
  • システムの活動を特徴づける
  • オブジェクトを挿入する
  • 論理条件と時制条件を決定する

 

そして,要求文では,「shall」「should」「will」を用いて、義務を定義できます.義務が変化した場合,要求も変化します.

 

義務の強さは,shall  >  should  >  will   の順です.

shall :     (絶対義務)   絶対に満たすべき要求であることを表す

should:  (義務)       絶対ではないが,高い確率で満たすべき要求であることを表す

will:    (可能義務)   できれば,満たすべき要求であることを表す

 

日本語で,shallshouldの区別は難しいと言えます.しかし,日本語でも,要求の義務の強さによって,「shall」「should」「will」に対応して,次のように書き分けることを意識してみてはいかがでしょうか.

(絶対義務)    システムは, 処理を 絶対に行う必要がある

(義務)            システムは, 処理を 行う必要がある

(可能義務)    システムは, 処理を 可能であれば行う

 

 

また,日本語では,英語のように使用する用語の違いで意味書き分けることが,難しい場合もあります.副詞の有無や文末だけの記述の違いで,要求の違いを明確に示すには限界もあるかもしれません.そういったときに,属性を付与することも1つの方法と言えます.たとえば,上記の [絶対義務], [義務], [可能義務] などを属性として,各要求に付与することを決めれば,要求文に補助情報を付けて,より明確化することになります.属性の例としては,他に,[必須要求](なくてはならないの意), [可能要求](あったほうがよいの意), [期待要求](なくてもよいの意)なども挙げられます.

こういった属性の記述は,自由度の高い自然言語の表現にある制約を付けて,意味を限定しようとするものであり,要求表現テンプレートの記述項目と言えます.

 

このように要求のテンプレートを決めることは,その使用を強制するわけではありません.テンプレートに合せて記述する訓練の機会を得ることによって,要求テンプレートを補助的なツールとして活用できるのではないでしょうか.

 

■文の構成要素を規定する要求構文

ISO/IEC/IEEE 29148:2011内「5.2.4 Requirements construct」では,表1に示すように3種類の要求構文の型を例示しています.この要求構文も要求テンプレートの例です.なお,日本語構文に合わせるために,助詞を補うとともに,語順を入れ替えています.

 

(構文の型1) [条件] [主体] [対象][制約] [活動]する必要がある.

例:信号x を受信したとき,   [条件]

  システムが,                   [主体]

  信号 xの受信ビットを       [対象]

  2秒以内で                   [制約]

  設定する                        [活動]

  必要がある

 

(構文の型2) [条件] [活動 または 制約] [値]である必要がある.

例:海の状態が 1のとき                                        [条件]

  レーダーシステムが目標を検知すべき範囲は,  [活動または制約]

  100 nautical マイルである                                  []

    .必要がある.

 

(構文の型3) [主体][値条件][活動] する必要がある.

例:請求書システム が                  [主体]

  昇順で,                         [値条件]

  支払いが保留中の顧客請求書を表示する  [活動]

  必要がある.

 

■要求テンプレートを使った要求文の例

たとえば,IREBによる義務の強さと,ISO/IEC/IEEE 29148:2011による要求構文を適用して,要求文を書いてみます.

 

(絶対義務) 

例:[主体] 交差点の信号機システムは,

  [値条件]  一方の信号機を赤に切り替えてから,

  [活動]        他方を青に切り替えることが,

                         絶対に必要である

 

(義務) 

例:[主体] 交差点の信号機システムは,

  [値条件] 一定時間,

  [活動]         両方の信号機を赤にすることが,

                        必要である

 

(可能義務) 

例:[条件]   両方の信号機が赤である時の一定時間は,

    [値]     3秒間とする

 (注)上記は、信号機システムの要求の一部のみを例示しています.要求として完全な記述ではありません.

 

このように,要求テンプレートを利用して,自然言語の記述の中で定型化できる箇所を整理し記述することは,読み手に対して要求を明確に伝える助けとなります.それ以上に,要求執筆者にとって,要求を整理し定義する際の1つの手立てとなります.


参考文献
[1] The home of Requirements Engineering, http://www.ireb.org/
[2] IREB Certified Professinal for Requirements Engineering - Foundation Level-Version 2.1 Dec.20th 2012
[3] 山本修一郎,IREBの紹介,http://www.bcm.co.jp/site/youkyu/youkyu111.html
[4] ISO/IEC/IEEE 29148:2011,Systems and software engineering-Life cycle processes-Requirements engineering.

 

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

 山本 修一郎

 

開発文書品質の研究というと耳新しく聞こえますが,開発文書の構文や構造,要求仕様テンプレートなど,研究の役に立ちそうな素材はこれまでに研究されてきた分野の中に転がっています.この連載コラム「山修の開発文書品質入門」では,開発文書に携わる皆さんに役立ちそうなそれらの知識を分かりやすく解説します.

バック・ナンバ

 

開発文書の品質を確認するためには,開発文書を読むための方法が必要です.普通の小説であれば,自由に楽しみながら読めばいいのですから,特別な方法に従う必要はありません.しかし,開発文書の場合には,ただ読むだけでは品質が高いのかどうかわからないものです.本稿では,開発文書を読むための方法を紹介します.

 

■文書から引き出された事実を読む

文書には,何かしらの事柄と,その事柄に基づく一連の出来事が書かれています.開発文書に書かれている内容は,開発の目的と,その目的を達成するためにこれからシステムとして実現すべき事柄です.とすると,開発文書を読むということは,開発の目的がどんなことであるかということと,システムを使う一連の操作によって,その目的が確かに達成できるということの2つを理解することでもあります.

もし,開発文書を読んで,システムが開発の目的を達成できると確認できれば,開発文書の信頼性は高いといえるでしょう.これに対し,開発文書を読んで開発の目的を達成できないことが確認できたとしたら,開発文書の信頼性は高いとはいえないでしょう.

システムが開発の目的を達成できるのかできないのかを読み取るためには,開発文書から引き出された「事実」に基づいて,それらから生じる可能性のある一連の出来事によって目的が達成できるかどうかを客観的に明らかにしていくような開発文書の読み方が必要になります.この過程では,期待や憶測を排除することが大切です.そうしないと,文書に記載されていない事柄に基づいて判断してしまうことになるからです.
文書に記述された事実に基づいて「システムを操作すると,どのようなことが生じるのか」を確認する方法を,「事実に基づく読解法」と呼ぶことにします.この方法はあえて名前を付けるほどでもないくらい単純なものなので,ソフトウェア工学の教科書にも出てきません.このコラムで初めて使った名称です.

 

■具体例

それでは,このコラムでいつもお世話になっているNPO法人 組込みソフトウェア管理者・技術者育成研究会(SESSAME)の要求仕様書「話題沸騰ポット」[1]の要求文を,事実に基づいて読解してみましょう.

読解に使う要求文を表1にまとめました.

 

表1 話題沸騰ポットの要求文の一部
 

 

この要求文[pot-220]を読むと,このポットが沸騰行為を行うためには,蓋を閉じた際に水位が条件に合う(水量が異常でない)という事実が必要だと分かります.また,[pot-280-11]を読むと,満水センサがonだと水量異常と判断されるという事実が分かります.さらに[pot-110-12]を読むと,満水センサのデフォルトがonだと分かります.

さらに,満水センサがoffになる契機を探すと,どこを読んでも出てきません.したがって,常に満水センサはonである(水量異常である)という事実が判明します.
これを整理すると,以下の一連の事実が明らかになります.

(事実1)満水センサのデフォルトはonである[pot-110-12]
(事実2)蓋センサがonになって3sec経過した時点で,満水センサはonを検出する.すなわち,このポットの許容上限を超えている(水量異常)と判断される[pot-280-11]
(事実3)蓋が閉じられても,水量が異常な場合,状態はアイドルのままである[pot-220-31]
(事実4)一つでも条件を満たしていなければ給湯できない[pot-260-11]
 

これらの事実から,以下の2つの結論を導くことができます.

(結論1)話題沸騰ポットはいつまでたっても沸騰しないポットである
(結論2)話題沸騰ポットは給湯ボタンを押しても給湯できない
 

表1に示したのは話題沸騰ポットの要求文の一部にすぎませんが,満水センサがoffになることについては,話題沸騰ポットの要求文のどこにも記載がありませんでした.したがって,満水センサは永久にonであることが,話題沸騰ポットの要求文から導かれる事実なのです.

ここで示した話題沸騰ポットの要求仕様書(第7版)は,「できる限り曖昧さを無くした仕様書の例として作成された」とのことです.この例から分かるように,開発文書の曖昧さをなくしたとしても,開発文書に欠陥がないわけではありません.曖昧さが無くても,入れた水を沸騰できず,給湯もできないポットになっています.話題沸騰ポットを開発する目的が,水を沸騰できるポットを実現することだとすると,この仕様書には明らかに欠陥があります.

ここまで,「事実に基づく読解法」によって開発文書を読む方法について解説してきました.ここでは要求文について議論しましたが,事実に基づく読解法は,さまざまな開発文書に適用できます.なお,要求文書をレビュする方法は,ここに紹介したやり方以外にもたくさんの方法があります.これらのレビュ手法についてもっと知りたい方は,要求工学連載の第37回[2]をご覧ください.

 


参考文献
[1] 組込みシステム教育教材 話題沸騰ポット GOMA-1015型 要求仕様書,http://www.sessame.jp/workinggroup/Wo ... up2/POT_Specification.htm
[2] 山本修一郎, 要求工学連載第37回,要求レビュ,http://www.bcm.co.jp/site/youkyu/youkyu37.html

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

山本 修一郎

開発文書の複雑さを計測するにはどうしたらよいでしょうか? 本稿では,開発文書の複雑さを,名詞句の個数に基づいて計測する方法[1]を紹介します.

■文書の複雑さの測定方法

文書を計測すると聞いてまず思いつくのは,ページ数や文字数を計測する方法です.また,文に含まれる単語を計測することもできます.単語には,接続詞や助詞などといった繰り返し出現する語も含まれます.助詞や接続詞は単独では意味を持たないので,これらを省いて名詞や名詞句,動詞だけを計測することもできます.名詞句(「寒い日」など)は,名詞(「日」)が指示する対象の属性や状態(「寒い」)を指定することができます.

基本的に,一つの文には一つの動詞が対応しているので,文の個数が動詞の個数に一致します(名詞句の中に出現する動詞は除く).同じ個数の文を含む複数の文書を比較した場合,動詞の個数は一致しますが,名詞句(名詞を含む)の個数は異なる場合があります.したがって,動詞の個数を計測するよりも名詞句を計測するほうが,文書の複雑さを計測するのに適していると考えられています.

■名詞句の例

例として,前回も参照したNPO法人 組込みソフトウェア管理者・技術者育成研究会(SESSAME)の「話題沸騰ポット 要求仕様書」[2]第7版の要求文に含まれる名詞句を調べてみましょう.

 


[pot-320] 設定されたモードの温度にポット内の水温を保持する.
 

 

この例文には,「設定されたモードの温度」と「ポット内の水温」という二つの名詞句があります.

■名詞句複雑度を定義する

N個の文からなる文書に,M個の名詞句が含まれているとします.同じ名詞句が文書の中で繰り返し出てくることがあります.そこで,すべての名詞句が文書の中で1回しか出てこない場合に対して,同じ名詞句が複数回出てくる場合の方が,文書の複雑さが小さいと考えると,次のように「文の名詞句複雑度」を定義できます.

 

[定義] 文の名詞句複雑度 NPC (Noun Phrase Complexity)
j番目の文に含まれる名詞句が,文書内で出現する回数の逆数の総和を,j番目の文に対する名詞句複雑度と呼ぶ.

 

わかりやすいように,具体例を挙げてみます.なお,こちらも話題要求ポット 要求仕様書の注意書きに一部手を入れて引用しました.

 


  この要求仕様書は,版数により,想定している用途が異なります.第1版~6版は,現実の開発現場でよく見受けられる曖昧さを含んだ仕様書として作成しました.曖昧部分に気づき,要求仕様書はどこまで詳細に分析し,明確に表現すべきかを考えていただける教材と考えています.第7版は,できる限 り曖昧さを無くした仕様書の例として作成しました.なお,私たちは,要求分析の最終段階ではこの記述レベルまで明確にすることを期待しています.
 

 

この文書は五つの文で構成されています.1番目の文には「要求仕様書」,「版数」,「想定している用途」という名詞句が含まれています.「要求仕様書」が文書内で出現する回数は2回なので,その逆数は1/2です.「版数」と「想定している用途」はそれぞれ文書内で1回ずつしか出現しないので,逆数もそれぞれ1です.つまり,1番目の文の名詞句複雑度は,2.5となります.ここでもし,2番目の文に含まれる「仕様書」を「要求仕様書」に変更すると,1番目の文の名詞句複雑度は2.3になります.

ここで,文についての複雑度の定義を基に,文書についての複雑度を示す指標として「文書の名詞句複雑度」を定義できます.

 

[定義] 文書の名詞句複雑度
文書に含まれる,文ごとの名詞句複雑度の総和を,文書の名詞句複雑度と呼ぶ.

 

例えば,N個の文からなる文書に名詞句が1個しかない場合(同じ名詞句を繰り返しており,動詞だけが異なる場合など),この文書の名詞句複雑度は1になります.一方,N個の文からなる文書にM個の名詞句があり,名詞句がそれぞれ1回ずつしか出現しない場合,この文書の名詞句複雑度はMになります.
したがって,文書の名詞句複雑度は,名詞句が文書内でどれだけ繰り返し出現するかによって減少するような尺度であるということができます.

■要求文の複雑度を計測する

それでは,話題沸騰ポット 要求仕様書 第7版に含まれる要求文を見ながら,この文書の複雑度を計測してみましょう.以下が,要求文の一覧となります.

 


[pot-210] コンセントの抜き差しで,ポットを利用できない状態/利用できる状態にする.
[pot-220] アイドルの状態で,蓋を閉じたら、水位を確認し,条件に合えば沸騰行為をする.
[pot-221] 蓋をあけたら(開いていたら),ロックは解除され,温度制御行為はしない.
[pot-230] 保温行為中で,沸騰ボタンを押すと,沸騰行為をさせる(沸騰できる).
[pot-240] 3種類の保温の温度に設定できる.
[pot-250] 給湯に対するロック/ロック解除機能を付ける.
[pot-260] 給湯ボタンを押すことによって給湯口から給湯する.
[pot-270] タイマボタンを押すことで,時間を分でセットし,タイマを起動できる.
[pot-271] タイマボタンを長く押すことで,タイマをリセットし,タイマを停止できる.
[pot-272] ユーザーが指定した時間がきたら,ブザーを鳴らして知らせる.
[pot-280] ポット内の水量をインジケータで表示する.
[pot-310] 水を沸騰させる.
[pot-311] カルキ抜きをする.
[pot-312] カルキ抜きが終わったら,保温行為をする.
[pot-320] 設定されたモードの温度にポット内の水温を保持する.
[pot-330] 沸騰行為も保温行為もできないときは温度制御はしない.
[pot-400] ヒータをon/offすることにより水温を制御する.その制御方式は制御周期と操作量(%)により行う.
[pot-500] 想定外の高温状態になった場合はエラーを検知し,ヒータ機能を停止する.
 

 

話題沸騰ポットの要求文の個数は18個です.この要求文には41個の名詞句があります.この中に,1回しか出現しない名詞句が35個,2回出現する名詞句が4個,3回出現する名詞句が2個ありました(図1の青い実線を参照).したがって名詞句の出現回数は49です.

ちなみに,2回出現する名詞句は,「蓋」「タイマボタン」「カルキ抜き」「保温行為」.3回出現する名詞句は「沸騰行為」と「タイマ」です.なお,名詞も修飾語のない名詞句として数えています.

 

図1 話題沸騰ポットの名詞句数と出現回数

 

上述した方法で,話題沸騰ポットの要求文18個に対する文書の名詞句複雑度を計算すると約41となり,名詞句の個数である41に近い結果になりました.したがって,名詞句複雑度から見ると,かなり複雑だということになります.

話題沸騰ポットの要求文に含まれる名詞句には類似するものもあるので,表現を見直すことにより,名詞句ごとの出現頻度を向上できる可能性があります.たとえば,繰り返し出現する名詞句を増やすことができれば(図1の赤い点線を参照),この要求文書に対する文書の名詞句複雑度を減らすことができます.

 


参考文献
[1] Chao Y. Din, Requirements Content Goodness and Complexity Measurement Based On NP Chunks, VDM Verlag Dr.Muller, 2008
[2] 組込みシステム教育教材 話題沸騰ポット GOMA-1015型 要求仕様書,http://www.sessame.jp/workinggroup/Wo ... up2/POT_Specification.htm
 

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

 

山本 修一郎

開発文書では,「分からないものを書く方が悪い」という姿勢が大切です [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)
  • 閲覧 (5460)

サイト内検索

カテゴリ一覧

ログイン

ユーザ名:

パスワード:

次回からIDの入力を省略



パスワード紛失