ASDoQ活動紹介～SWEST21予稿～
2019.9.5-6
ASDoQ運営委員

1

ASDoQ• システム文書品質研究会（ASDoQ：Association of System Documentation Quality） H23.7～• 目的
Webでご入会を受付中
1. 開発文書の品質の定義
2.
3.

• 活動
• 特徴





開発文書の品質を測る方法の研究
開発文書の品質を向上させる方法の研究

https://asdoq.jp/

大会(1回/年)，ワークショップ(1回/年)，研究会(3回程度/年)
参加費無料
会員の多様性．業務や専門領域は異なるが，全員が，文書品質に関心を持つ
会員数
代表幹事
山本雅基
名古屋大学
アドバイザ
高田広章
名古屋大学
‣法人：23社
アドバイザ
田丸喜一郎
スキルマネージメント協会‣個人：123名
アドバイザ
山本修一郎
名古屋大学
運営スタッフ：13名

運営ボランティア募集中．
社会貢献にご協力ください．
右のスタッフに，お声がけを．

幹事，事務局長 藤田悠
幹事
栗田太郎
幹事
小林直子
幹事
塩谷敦子
運営委員
粕渕清孝
運営委員
奈良慶之
運営委員
森川聡久
運営委員
山崎伸洋
会計監査
中澤達夫

長野工業高等専門学校
ソニー(株)
エプソンアヴァシス(株)(合)イオタクラフト(株) SCREENアドバンストシステムソリューションズ(株)ベリサーブ(株)ヴィッツ
住友電気工業(株)長野工業高等専門学校

2

活動成果
• 公開情報（https://asdoq.jp/research.html）
システム開発文書品質モデル（Ver.1.1）
用語集(Ver.0.0)
ASDoQ White Paper
ソフトウェア要求仕様書のサンプル• 会員限定情報

開発文書品質の特性の整理
文書作成技術の一覧
システム開発技術の一覧
用語集Wiki
良い例文・悪い例文• その他，大会やワークショップや研究会で得られた無形の価値
 討議，気づき，人脈…
さまざまな広がり3

開発文書品質を読み手の立場で考える

情報品質

記述品質

読み手は，開発文書を次の順で取り扱う（Step1）「認識」

文章，図形などを読み取り，内容を表層的に認識する（Step2）「理解」

他の情報または既知の知識と関連づけて，深い水準で理解する（Step3）「行為」

得られた情報を用いて，読み手は担当業務を遂行する

Step1から３にかけて求められる品質は，「記述品質」から「情報品質」へ徐々に変化する．
情報品質
行為
得られた情報を用いて，担当業務を遂行する

記述品質
理解
他の情報または既知の知識と関連づけて，深い水準で理解する

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

開発文書
4

品質特性を段階的に割り当てる5種類の品質特性
品質特性(1)完全性(2)論理性(3)理解容易性(4)可読性(5)規範適合性
(1)

(2)

説明
開発に必要十分な情報が記載されている
論理的に整合が取れている
理解しやすい読みやすい
記述が標準または規則に準拠している
(3)

(4)

(5)

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

5

システム開発文書品質モデル(Ver.1.1)
品質特性
行為

理解

品質副特性

測定項目（例）

完全性

合目的
正確
妥当

読み手の明示技術が正しく実現可能許容範囲で開発可能

論理性

無矛盾
一貫
構造

項目間の矛盾がない
理由または根拠の明記
階層が合理的

理解容易性

非曖昧性
関係

複数の解釈が成り立たない
参照先を正しく明示

可読性

簡潔
統一
表記工夫

一文一義
視点の統一
箇条書きを適切に使用

規範適合性

文法適合
記法適合
基準適合

誤字脱字がない
箇条書きのルールに適合
テンプレートに準拠

認識• 上記の「測定項目(例)」を増やしたシート (ダウンロード可能) https://asdoq.jp/research.html• 以下の論文で，品質モデルの概要と試行した課題を論じている
 「システム開発文書品質モデル活用への取組み」情報処理学会デジタ
ルプラクティス Vol.8 No.2 (Apr. 2017)
http://www.ipsj.or.jp/dp/dp-index.html（閲覧無料）6

養成システム開発文書品質モデルの活用場面
開発プロセスの例（ESPR）

プロセスを構成する工程の例（ソフトウェア要求定義工程）

文書品質モデル

レビューを支援する

情報伝達に活かす～書き手と読み手をつなぐ～

文書品質モデル

書くときの基準を定める

文書品質を測定する
文書品質モデル
文書品質モデル

読み書きのスキルを養成する

文書品質モデル

プロセス図の引用：IPA/SEC「改訂版組込みソフトウェア向け開発プロセスガイド」

7

レビューを支援する• セルフレビュー


自分が「苦手な品質特性」だけを点検する• 非公式レビュー

先輩技術者が「完全性」を点検する
後工程の技術者が「理解容易性」を点検する• 公式レビュー

レビューの合否を品質特性ごとに定める• 工程（アクティビティ）ごとに注目する特性を定める


実装を海外発注する時の設計書レビューでは，「規範適合性」により多くの注意を払う• 開発文書の章単位に注目する特性を定める


システムの概要を記載する章では「全体から部分へ」という「論理性：構造」を重視するモジュール設計を行う章では「完全性」を重視する

8

モデルを拡張してレビューに使う• 欠陥重要度を拡張したシステム開発文書品質モデル


欠陥重要度を，例えば，以下のようにレビューの合否別にランク付けする‣A：不合格．指摘を必ず修正する．さらに，修正後にレビューが「必要」‣B：合格．ただし，指摘を必ず修正する．修正後のレビューは「不要」‣C：合格．指摘の修正義務はない．今後，同様の指摘を受けないように注意• レビュー指摘を分類する


文書品質特性 x 欠陥重要度 のマトリックスに，レビュー指摘を分類する．

9

レビュー時にモデルに期待すること• プロジェクト管理での活用： 品質特性の傾向から，プロジェクトの運営をカイゼンする
 例えば，請負開発の要求定義工程レビューで，非曖昧に対する指摘件数の比率が，他のプロジェクトに比べて高いことが分かった．
この場合は，顧客からの要求が明確になっていない可能性が高い．
そこで，曖昧な要求に対しては，請負側で明確な案を作り，顧客に提案する取り組みを推進する．
• レビュー振り返りの活用： 品質特性の傾向を分析してカイゼンする
 例1：我が社においては，レビュー不合格とする指摘が，完全性と論理性だけであり，理解容易性や可読性などに対する指摘があっても合格としていることが分かった．
⇒公式レビューでは，完全性と論理性のみのレビューを行い，その他の特性に関する指摘は，非公式レビューで行う．公式レビューの負荷を下げて効率化する．
 例２：理解容易性や可読性の指摘が多いと，完全性の質が低い傾向が確認された．
⇒測定が比較的容易な理解容易性と可読性から，測定が困難な完全性を推定する．そして，完全性の推定値が低いが，実際のレビューで完全性の指摘が少ない場合は，レビュー時の見落としがないかを見直す．
10書くときの基準を定める• 「規範適合性」の高い文書を書く

ツールと人手で分担して効率よく規範適合性を満たす‣例：まず，満たすべき規範適合性の項目を列挙する．
次に，その中からWord文章校正機能に含まれる項目を抽出する．
執筆中にツールでそれらの項目に対する違反を検出し校正する．
人手では，残りの項目違反だけを検出し，校正する．

• 「可読性」の高い文書を書く

自分なりの「表記工夫」を作る‣例：箇条書きで手順を書くときには， (Step1)(Step2)と項目の前に書く．文書テンプレートは，会社の基準が許す範囲で，箇条書きの記号や本文のインデント文字数などをカスタマイズする• 「理解容易性」の高い文書を書く

曖昧な書き方の癖を克服する‣例：レビューで「非曖昧」に分類される指摘を受けた場合，それを元にして「私が書きがちな曖昧な文例」を作る．以降，その文例と同様な書き方をしないように，注意する．
11情報伝達に活かす～書き手と読み手をつなぐ～• 伝わりにくい文書から学ぶ


後工程からの質問数を品質モデルの特性ごとに集計‣後工程からの質問数が多い特性を，伝わりにくい特性とみなす⁃
書き手と読み手が対話して，伝わりにくい理由を共有する> 書き手は，書き方を改訂する．
> 読み手の読む能力が低い場合は，読む訓練を受ける．

伝わらなかったとき，その失敗を無駄にしない‣例：納入してから，要求仕様の理解が，開発者と顧客でズレていたことが判明する場合もある．次の開発のためにも，正しく伝わらなかった原因分析をして，正しく伝える対策を考える．

• 伝わりやすい文書から学ぶ

読み手が「可読性」「理解容易性」を評価しながら読む‣可読性と理解容易性の質は，書き手の基礎的なライティング能力に依存する点が多い．読み手は，異なる書き手による複数の開発文書を読むので，各文書の質の良し悪し（わかりやすさや，的確さなど）を認識しやすい．読み手が，文書を評価し，質の良い開発文書を横展開するように，PMに進言する．

12

文書品質を測定する• 特性・副特性ごとに欠陥を集計する


欠陥数を計数する‣例：この文書の欠陥は，規範適合性が10件，可読性が30件…
⁃
特性・副特性の分類に迷う場合の対応案(1)いずれかに分類(2)等分して計数（例：可読性1/2件，理解容易性1/2件）



欠陥の重要度を求める（品質モデルに重要度の拡張をした場合）‣例：規範適合性では，重要度大が0件，中が2件，小が8件…



特性・副特性ごとの品質を，人手で評価する‣例：規範適合性の品質は4点（5点満点で評価する場合）‣例：規範適合性の品質は合格（合否で評価する場合）• 総合的な品質を評価する


特性・副特性ごとの測定結果を踏まえて，人手で評価する‣例：文書品質の総合点は4点（5点満点で評価する場合）‣例：文書品質は合格（合否で評価する場合）

13読み書きのスキルを養成する• 弱点を分析して育成に活かす

後工程からの質問数を品質モデルの特性ごとに集計
レビューの指摘数を品質モデルの特性ごとに集計‣質問や指摘の件数の多い特性を，書く時に注意するべき．一般的なライティング教育を受講したり，質問や指摘が出ないようにするにはどうすれば良かったかを討議する演習などを行う．

• 読み書きのスキルを高めるように仕事を進める顧客（受注先）が書く要求仕様書の傾向を評価し対応する‣例：顧客から「非曖昧」の品質が低い文書を受け取った経験がある
場合は，新しい仕事の場合でも，彼らの要求仕様書に曖昧な記述があることを仮定して読み込む．そして，要求を明確にするように交渉する．

協力会社（発注先）が書く月例報告の傾向を評価し対応する‣例：月例報告に客観的な根拠に基づいて進捗が書かれていないならば「完全性」が不十分であると判断する．そして，報告事項を明確に指示するように，外注管理を改める．
14

モデル利活用での注意とお願い• ご注意：モデルの利活用はこれからで，まだ良くなります

モデルを用いる目的を絞る‣モデル適用の目的を絞り込む方が，適用の効果を議論しやすい．

実用的である‣実用性が高い活用方法の方が，現場で使われるはず．
‣例えば，文書品質の良し悪しをはかるチェックリストを200個作り，全てを同じ慎重さでチェックすることは，現実的ではない．

完全主義者や評論家にならない‣「まだできないこと」より「少しはできたこと」に焦点を当てるべき．不完全な部分を批評するだけではなく，カイゼンの種にする．

• お願い：ASDoQにフィードバックしてください

可能な範囲で結構です．情報をお寄せください．大会や研究会でご報告ください．
‣モデルをこんなところに，こうやって使い，こんな効果があった．
‣モデルのココにこんなカイゼンをした．
ご連絡先：secretariat@asdoq.jp

15