s4aシステム開発文書の品質を考えよう
SWEST 17
ASDoQ（システム開発文書品質研究会）

システム開発文書品質研究会

Association of System Documentation Quality

ASDoQ
名称

システム開発文書品質研究会

略称

ASDoQ (Association of System Documentation Quality)アスドック

Web

http://asdoq.jp/

種別

任意団体

設立

2011年7月11日

会員

個人会員（87名），法人会員（18社）（2015.7現在）

会費

原則無料

活動

定期研究会 ：

一年に3～4回
技術発表，作業部会の報告

ASDoQ大会 ：一年に１度開催

ワークショップ：

特定のテーマを合宿で集中討議

作業部会

具体的な課題に取り組む．

システム開発文書品質研究会：

Association of System Documentation Quality

プログラム
13:00 – 13:10
13:10 – 13:30
13:30 – 14:00
14:00 – 14:15
14:15 – 14:20
終了 14:20

システム開発文書品質研究会

１．オープニング
２．文書品質モデルの紹介
３．グループ演習
測定項目の洗い出し
４．発表
５．クロージング

Association of System Documentation Quality

２．文書品質モデルの紹介

２．１ システム開発文書と，書き手および読み手の関係
システム開発文書品質研究会

Association of System Documentation Quality4開発文書の書き手および読み手
開発文書の役割：開発に必要な情報を記録して伝える– 書き手• 担当業務の成果を，開発文書に表現する
例：設計者が設計書を書く– 読み手• 開発文書を理解し，自分の担当業務を遂行する
例：プログラマが設計書を読みプログラミングをする担当業務で作り出された情報開発文書を通じて読み取った情報
表現

理解

開発文書
システム開発文書品質研究会

Association of System Documentation Quality

5開発文書の品質は読み手が決める• 利用者（読み手）が利用目的に応じて品質を決める• 読み手の利用目的：担当業務を遂行するため• 例１：設計者は，上位仕様書（例：ソフトウェア要求仕様書）を読み設計する．設計に必要な情報を求める• 例2：日本語を母語としない国外の実装者は，日本企業からの発注仕様書を読み実装する．彼らは，明確な日本語を求める．

• 全ての利用目的に共通する開発文書の品質
1. 情報品質担当業務を遂行するために提供される情報の良し悪し

2. 記述品質
記述を読み取り理解するまでの負荷の高低システム開発文書品質研究会

Association of System Documentation Quality6読み手による開発文書の利用手順

情報品質

記述品質

読み手は，開発文書を次の順で取り扱う（Step1）「認識」
文章，図形などを読み取り，内容を表層的に認識する（Step2） 「理解」
他の情報または既知の知識と関連づけて，深い水準で理解する（Step3） 「行為」
得られた情報を用いて，読み手は担当業務を遂行する

Step1から３にかけて求められる品質は，「記述品質」から「情報品質」へ徐々に変化する．
情報品質

記述品質
理解

行為
得られた情報を用いて，担当業務を遂行する

他の情報または既知の知識と関連づけて，深い水準で理解するシステム開発文書品質研究会

認識
文字，図形などを読みとり，内容を表層的に認識する

Association of System Documentation Quality

開発文書
7

２．文書品質モデルの紹介

２．２ システム開発文書品質モデル

システム開発文書品質研究会

Association of System Documentation Quality

8

(Step1)(Step2)(Step3)における品質• (Step1)「認識」，(Step2)「理解」 における品質– 多くの実用的な文書に共通する品質．他の基準類でも言及される– システム開発に特化した記法に関する品質は，システム開発文書品質として特徴的である– QCD (Quality, Cost, Delivery)の「C」と「D」に強い影響を与える• (Step3)「行為」 における品質– システム開発に必要な情報の質を問う– システム開発文書品質に固有な品質– QCD の「Q」に強い影響を与えるシステム開発文書の特徴的な品質
情報品質

記述品質
理解

行為
得られた情報を用いて，担当業務を遂行する

他の情報または既知の知識と関連づけて，深い水準で理解するシステム開発文書品質研究会

認識
文字，図形などを読みとり，内容を表層的に認識する

Association of System Documentation Quality

開発文書
9

システム開発文書品質モデル
システム開発文書品質モデルは，次の3層で構成する• 第1階層：品質特性– 文書品質の大分類を示す• 第2階層：品質副特性– 各品質特性に含まれる小分類としての副特性を示す• 第3階層：測定項目– 品質特性・品質副特性の測定を行う項目
品質特性

システム開発文書品質システム開発文書品質研究会

品質副特性

測定項目

システム開発文書品質モデル

Association of System Documentation Quality

10第1階層：品質特性
品質特性を，5種類に分類する
品質特性(1)完全性(2)論理性(3)理解容易性(4)可読性(5)規範適合性
(1)

(2)

説明
開発に必要十分な情報が記載されていること
論理的に整合がとれていること理解しやすいこと読みやすいこと
記述が文法や規則に則していること
(3)

(4)

(5)

「認識」から「行為」に向けて，特性を段階的に割り当てる(1)は，システム開発文書として，特徴的な品質．
(2)-(5)は，多くの実用的な文書に共通する品質．

システム開発文書品質研究会

Association of System Documentation Quality11

第2階層：品質副特性
品質副特性を，14種類に分類する
品質特性 品質副特性
合目的
完全性

論理性

説明
読み手と目的を明示している
目的に合致した内容を記述している

正確記述内容が正しい妥当

記述内容が妥当である

無矛盾

論理的な衝突（矛盾）がない

一貫

論理展開が合理的で一貫している構造

内容の整理が合理的・体系的である
一意に解釈できる（一意性）

理解容易性

可読性

規範適合性

非曖昧

動作または状態を特定できる（具体性）

関係

各情報間の関係が明確である

簡潔

短文で，かつ簡潔に記述している

統一

表記・表現方法および表現上の視点が統一されている

表記工夫

内容の理解と解釈を助けるために，表記上の工夫がある

文法適合

言語の文法に則している

記法適合

各種の設計表記法（状態遷移表，UMLなど）や標準記法などに則している

基準適合

組織で定められた基準または標準に則しているシステム開発文書品質研究会

Association of System Documentation Quality12

第3階層：測定項目 (1)完全性
開発に必要十分な情報が記載されていること
品質副特性説明

測定項目

読み手と目的を明示している

合目的

・文書の読み手（開発技術者，テスト技術者，発注者など）の明示
・文書の使用範囲（提出先, 配布先, 開示範囲）の明示
・文書の読み手に要求する条件（開発経験，保有スキルなど）の明示
・開発の目的の明示（開発のスコープを含む．例：要求仕様書に開発の目的を書く）
・開発文書の目的の明示（例：実装に加えて将来の改訂開発を想定した設計書）
・記述単位（章・節・項・段落・図・表）の目的の明示
・関連情報（工程，入力文書など）の明示

・記述内容が文書の目的に合致・個々の記述単位(章・節・項・段落・図・表）の内容が各目的に合致
・目的を達成するために必要な，情報，条件および項目の記載
目的に合致した内容を記述して ・目的を達成するために，理解しておくべき方針や意図の記載（例：設計書には設計方針を書くこいるとを推奨する）
・記述に漏れが無い・目的に適合する内容のみの記載
・読み手の条件（開発経験，暗黙知など）を満たせば，読み手が目的を達成できる内容

正確記述内容が正しい・技術が正しく，実現可能

妥当

記述内容が妥当である

・開発プロジェクトが許容する資源の範囲で開発可能
・TBDを解消する決定時期・決定方法の明記（注）上記の測定項目は例である．システム開発文書品質の測定を行う際にはカスタマイズすること．

システム開発文書品質研究会

Association of System Documentation Quality

13

第3階層：測定項目 (2)論理性
論理的に整合がとれていること
品質副特性
無矛盾

一貫

構造

説明

測定項目

論理的な衝突（矛盾）がない

・項目間の矛盾がない
・条件間の矛盾がない

論理展開が合理的で一貫している・上位と下位と，原因と結果とが対応
・理由または根拠の明記
・記述間や文書間の整合性がとれ，追跡可能内容の整理が合理的・体系的である・全体像を明示した後に詳細が記述されている（目次、全体構造の提示など）
・記述単位の見出しと内容とが合致
・粒度が揃っている・階層が合理的（例：木構造，is-a，has-aなどを適切に使い分ける）
・内容に関する無駄な重複がない（注）上記の測定項目は例である．システム開発文書品質の測定を行う際にはカスタマイズすること．

システム開発文書品質研究会

Association of System Documentation Quality14

第3階層：測定項目 (3)理解容易性
理解しやすいこと
品質副特性

説明
一意に解釈できる（一意性）

・複数の解釈が成り立たない
例1：複数の解釈が成り立つ接続語，否定表現などが利用されている（「～し（帰結・追加）」「すべて～でない（全部・部分）」）
例2：係り受け（修飾する・される）の関係が明確でない

動作または状態を特定できる（具体性）

・動作や状態などを特定
例：動作（「処理する」「制御する」など），状態（「正常」「異常」など），性質(「速い」「大量の」など）
・値や範囲などを定義
・専門用語や略語などの用い方を定義

各情報間の関係が明確である

・参照先や引用元を正しく明示
・既知の知識に関連付く手がかりの記述
・宣言や定義には，その理由や根拠の記述

非曖昧関係

測定項目

（注）上記の測定項目は例である．システム開発文書品質の測定を行う際にはカスタマイズすること．

システム開発文書品質研究会

Association of System Documentation Quality

15

第3階層：測定項目 (4)可読性
読みやすいこと
品質副特性

説明

測定項目
・一文一義
・修飾語と被修飾語の距離が短い
・できるだけ肯定表現を使用し，二重否定は使用しない
・記述に重複がない

簡潔

短文で，かつ簡潔に記述している

統一

表記・表現方法および表現上の視点が統一され ・文体（例：ですます調，である調など），用語および表記法の統一ている
・視点の統一（例：主語をシステムに統一して記述する）

表記工夫

・箇条書きまたは図表を適切に使用
・インデント，改行および空行の使用による読みやすさの向上
内容の理解と解釈を助けるために，表記上の工・読点の適切な使用による文章構成の明確化
夫がある
・読みやすいレイアウトやフォント種の使用・不必要なカタカナ表現を使用しない（注）上記の測定項目は例である．システム開発文書品質の測定を行う際にはカスタマイズすること．

システム開発文書品質研究会

Association of System Documentation Quality

16

第3階層：測定項目 (5)規範適合性
記述が文法や規則に則していること
品質副特性

説明

測定項目

文法適合

言語の文法に則している

・誤字脱字がない
・主語と述語と，かつ，目的語と述語とが対応・接続詞，助詞などを正しく使用

記法適合

各種の設計表記法（状態遷移表，UMLなど）や標準記法などに則している・箇条書きのルールに適合・図の記載ルールに適合

基準適合組織で定められた基準または標準に則し ・テンプレートに準拠ている
・適用すべき基準または標準に準拠（注）上記の測定項目は例である．システム開発文書品質の測定を行う際にはカスタマイズすること．

システム開発文書品質研究会

Association of System Documentation Quality17

２．文書品質モデルの紹介

２．３ カスタマイズしてご使用下さい

システム開発文書品質研究会

Association of System Documentation Quality

18

「測定」し「評価」する

開発文書

測定

評価

尺度に基づいて，品質を点数化すること

測定結果を元に，品質の良し悪しを判断すること．

補足：「測定」「評価」の他に総括的評価として「評定」を加える場合もあるが，本資料では省く．

品質は利用者（読み手）が利用目的に応じて決める．
測定項目，測定値の求め方，評価基準をカスタマイズするシステム開発文書品質研究会

Association of System Documentation Quality19測定値の求め方• 機械による測定，および人手による測定がある• 機械による測定（例）– 規範適合性および可読性• 外形的な計測（例：文字数，ページ数）• 不適切な助詞の使用法の検出（例： 「の」の連続）• 人手による測定（例）– 機械に未登録なライティング規則の検出（例：TC協会(*)が定めるライティング規則の多く）– 意味解釈を必要とする測定（例：完全性）

機械および人手を使い分けて，目的を満たす効率および精度で測定する(*) 一般財団法人テクニカルコミュニケーター協会

システム開発文書品質研究会

Association of System Documentation Quality

http://www.jtca.org/20

人手による測定の例• 品質特性（または品質副特性）に対応して測定– チェックリストを用いた測定• 品質特性（または品質副特性）毎にチェック項目を設定し，チェック数を数える• 例：完全性 - 正確
□ 技術的に誤りがある
完全性 - 妥当
☑ TBDを解消する期限が設定されていない– 質問紙を用いた測定• 例：複数の選択肢から一つを選択する
とてもそう思う

そう思う

どちらでもない

あまり思わない

ぜんぜん思わない

設問：完全性 - 合目的
読み手と目的を明示していますか？
設問：完全性-正確記述内容が正しいですか？

システム開発文書品質研究会

Association of System Documentation Quality21測定値のまとめ上げ• システム開発文書品質モデルは，複数の特性から構成される．
総合品質は，複数の特性値を重み付けしまとめ上げて求める．
• 品質特性は，複数の品質副特性から構成される．
特性値は，複数の品質副特性値を重み付けしまとめ上げて求める．
• 品質副特性には，複数の測定項目を設定し得る．
品質副特性値は，複数の測定項目の測定値を重み付けしまとめ上げる．
品質特性の一つである論理性値のまとめ上げ例
Step1. 測定項目の設定
Step2. 副特性の重み付け
右表カッコ内．合計を1とする．
Step3. 測定項目の重み付け
右表カッコ内．合計を1とする．
Step4. 測定項目毎の測定値を算出
項目毎に10点満点で採点
Step5. 副特性の測定値を算出
測定項目の測定値に重みを乗じて平均する
Step6. 特性の測定値を算出
副特性の特性値に重みを乗じて平均するシステム開発文書品質研究会

品質
特性

論理性

品質
副特性

測定項目

無矛盾(0.3)

・項目間の矛盾がない(0.5)
・条件間の矛盾がない(0.5)

一貫(0.2)・制御ロジックの理由または根拠を明記(0.4)
・ISO26262のトレーサビリティ要求に合致 (0.6)

構造(0.5)・全体像→詳細の順で書かれている (0.2)
・階層が合理的(0.5)
・無駄な重複がない(0.3)（注）上記の測定項目は，p17の例をカスタマイズして用いている

Association of System Documentation Quality22

評価基準を定めて評価する
利用目的に応じて，評価する
Step1. 評価を行う単位（測定項目，品質副特性，品質特性，総合品質）で，評価基準を定める．
Step2. 測定項目が，利用目的に適していることを確認する．
Step3. 測定値の求め方が，利用目的に適していることを確認する．
Step4. 測定値および測定値をまとめ上げた値と，評価基準とを比較し，利用目的に対応した評価を行う
例：品質特性「論理性」を評価する
規格Aの基準値

社内の基準値論理性
文書B
文書Bは，規格Aを満たしているが，社内基準を満たしていない．

システム開発文書品質研究会

Association of System Documentation Quality

23

連絡先
実際の測定および評価活動を通じて課題を抽出しシステム開発文書品質モデルを改訂します• システム開発文書品質モデルのご意見は，以下へご投稿下さい– http://asdoq.jp/research.html• お問合せはASDoQ事務局へE-mailでお願いします– ASDoQ事務局 secretariat@asdoq.jp

システム開発文書品質研究会

Association of System Documentation Quality24

３．グループ演習• 測定項目を定める効果– 測定項目には，次の使い方があります．
• 測定：文書品質を測るときに，この項目を使用する• 作成：文書を作成する際に，この項目に注意する• 討議項目– 新しい測定項目を考えよう

システム開発文書品質研究会

Association of System Documentation Quality

メモ(1)完全性(2)論理性(3)理解容易性(4)可読性(5)規範適合性

システム開発文書品質研究会

Association of System Documentation Quality