設計書作成と作業形骸化
をテンプレートにして作成
[
トップ
] [
新規
|
一覧
|
単語検索
|
最終更新
|
ヘルプ
]
開始行:
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicros...
-[[戻る>ドキュメンテーション]]
--設計書作成と作業形骸化
--[[リエンジ用途でリバース・ツールを利用]]
* 目次 [#l667ed72]
#contents
*概要 [#qe09faeb]
-基本的に、設計作業や、その後のテスト作業に必要となる~
仕様書・設計書の類は、リバースせず設計者によりブレークダ...
-(Windows Forms, Web Formsなど、構造が定まり易い)フレー...
ブレークダウンの作業が形骸化してしまう類のドキュメント~
(特に、クラス・メソッド一覧系や、クラス・メソッド定義書...
のみ[[ドキュメンテーション・ツール]]を適用してリバースす...
--Windows Forms, Web Formsなど~
画面単位のモジュール化、コンポーネントベース、イベント・...
などを実現するフレームワークを活用する場合、詳細設計作業...
モジュール設計作業の形骸化が発生することがある。~
--MVCなどの柔軟性の高いフレームワークを使用する場合、~
モジュール設計作業工程が重要になるケースもある。~
大規模開発でMVCが標準のJavaを使用するケースなどでは、~
モジュール設計書から、スケルトンの自動生成をしている事が...
*事例 [#p3adf6f6]
-[[フォワードの事例>#jdbdcd23]](モジュール・レベルの詳細...
-[[リバースの事例>#mafe6bac]](モジュールからドキュメント...
**フォワードの事例 [#jdbdcd23]
フォワードとリバースの両面を採用する理由としては、~
進捗管理や設計能力の確認などが含まれるようです。
「設計者のスキルが把握できていれば、完全リバースでもリス...
そうでない場合は製造する対象物(ファイル、クラス、メソッド...
明確にししないと、製造物の進捗も管理できませんし、設計能...
***問題 [#c0cfb12b]
(Windows Forms, Web Formsなど、構造が定まり易い)フレー...
フォワード(モジュール・レベルの詳細設計書作成)の際にや...
-工程を圧迫し、品質が問題になった。
-また、設計書を作る(=こなす)のが目的~
になってしまい、作業の形骸化が起こった。
という問題が事例ベースで報告されていますが、こう言った~
作業経験がある方は、想像に難くない内容かと思います。
***分析 [#b1730246]
-クラス・メソッド仕様書記述の意味合いも良く検討する。~
従来の手法は、設計に時間をかけて品質を出しているに過ぎな...
--具体的な事例に、1stepに対応する仕様書を書くという方法が...
--ただし、コレは、顧客予算が対応しなければ成立しない方法...
-IDEを使用してモジュールのスケルトンを作成し~
[[ドキュメンテーション・ツール]]でリバースするという方式...
--業務レベルの設計を行う人間にモジュール設計まで担当させ...
--雑にやっても、どの道、プログラム・レベルの設計で覆され...
***図表の利用 [#bf1f9a49]
イベントフロー、アクティビティ図(≒フローチャート)の事例
-問題
--ここまでのフォワード(モジュール・レベルの詳細設計書作...
イベントフロー、アクティビティ図(≒フローチャート)などか...
自動生成する位は考えないと、生産性が上がらないという意見...
--「一度 Word、Exel で設計していたプロジェクトにこれらを...
修正や設計に手間がかかる割には、製造・テスト工程の生産性...
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下...
-対策~
「ソースコードを自動生成する位は考えないと、生産性が上が...
--構造化言語というツールもあるが、仕様書は自然言語で記述...
(自然言語で問題ないため、ワザワザ他のツールを導入する動...
--UML(イベントフロー、アクティビティ図)などを納品物とし...
これら重複が「自然言語で書かれたドキュメント」と比較する...
---何を代替するのか?
---優れているか劣っているか?
-一部、業務アプリケーション開発の用途でも効果的なダイアグ...
--シーケンス図(アーキテクチャ説明、モジュール構成説明)
--状態遷移図(状態ごとの制御が複雑なプログラムの説明)
--ディシジョン・テーブル or ツリー(ディシジョンの説明)
-従って、上記の様な自然言語で表し難い仕様を説明する~
これらのダイアグラムを必要に応じて作成する場合は、~
補足説明書として付属させても形骸化は発生しません。
**リバースの事例 [#mafe6bac]
比較的多くの案件で採用されている。~
(業務的詳細設計書と方式設計書をコーディング工程で結合す...
モジュール・レベルの詳細設計書はリバース生成させる。
***問題 [#xd872266]
Doxygenを採用(A Hot Document等で代替も可能)し、~
メソッド内コメントのコメント規則を整備して~
設計書をリバース生成させる方式を導入したが定着せず。~
***分析 [#o7e4e5b2]
理由は以下
-イベント仕様書記述(業務的詳細設計書)で~
足りる(わざわざリバース生成する必要が無い)
-リエンジ用途(リエンジの詳細は後述)
--としては不完全である。
--として活用するのは先(将来)の話になってしまう。
-以下の様に、コメントの振り方が変わってきてしまう。
--以下がプログラム内に混在
---内部文書化目的のコメント(一般的なコメント)
---リバース生成目的のコメント
--このため、メソッド冒頭にメソッド仕様を纏めて記述するな...
製品など、納品やリエンジ用途ではなく自分のために使用する...
リバース生成方式の採用を本格的に検討しても良いかもしれま...
***納品用途 [#rd8e07ed]
モジュール・レベルの詳細設計書の納品を求められるケース
-必要不可欠というものではなく、作業形骸化を起こすため問題...
-前述の[[イベントフロー、アクティビティ図>#bf1f9a49]]で説...
>「修正や設計に手間がかかる割には、製造・テスト工程の生産...
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下...
>という状態に陥ることになります。
-これでも、クラス・メソッド仕様書を納品物として求められる...
--リバース・ツールの生成する形式ではなくExcel形式で要求さ...
--手書きでフォワードしたもののみ認められる見積条件の場合...
***リエンジ用途 [#kd670643]
[[リエンジ用途でリバース・ツールを利用]]するのは、だいた...
*参考 [#z38ab040]
**Open 棟梁 Wiki [#c95dae93]
***[[ドキュメント標準のポイント>https://opentouryo.osscon...
----
Tags: [[:ドキュメンテーション]], [[:その他、開発の色々]]
終了行:
「[[マイクロソフト系技術情報 Wiki>http://techinfoofmicros...
-[[戻る>ドキュメンテーション]]
--設計書作成と作業形骸化
--[[リエンジ用途でリバース・ツールを利用]]
* 目次 [#l667ed72]
#contents
*概要 [#qe09faeb]
-基本的に、設計作業や、その後のテスト作業に必要となる~
仕様書・設計書の類は、リバースせず設計者によりブレークダ...
-(Windows Forms, Web Formsなど、構造が定まり易い)フレー...
ブレークダウンの作業が形骸化してしまう類のドキュメント~
(特に、クラス・メソッド一覧系や、クラス・メソッド定義書...
のみ[[ドキュメンテーション・ツール]]を適用してリバースす...
--Windows Forms, Web Formsなど~
画面単位のモジュール化、コンポーネントベース、イベント・...
などを実現するフレームワークを活用する場合、詳細設計作業...
モジュール設計作業の形骸化が発生することがある。~
--MVCなどの柔軟性の高いフレームワークを使用する場合、~
モジュール設計作業工程が重要になるケースもある。~
大規模開発でMVCが標準のJavaを使用するケースなどでは、~
モジュール設計書から、スケルトンの自動生成をしている事が...
*事例 [#p3adf6f6]
-[[フォワードの事例>#jdbdcd23]](モジュール・レベルの詳細...
-[[リバースの事例>#mafe6bac]](モジュールからドキュメント...
**フォワードの事例 [#jdbdcd23]
フォワードとリバースの両面を採用する理由としては、~
進捗管理や設計能力の確認などが含まれるようです。
「設計者のスキルが把握できていれば、完全リバースでもリス...
そうでない場合は製造する対象物(ファイル、クラス、メソッド...
明確にししないと、製造物の進捗も管理できませんし、設計能...
***問題 [#c0cfb12b]
(Windows Forms, Web Formsなど、構造が定まり易い)フレー...
フォワード(モジュール・レベルの詳細設計書作成)の際にや...
-工程を圧迫し、品質が問題になった。
-また、設計書を作る(=こなす)のが目的~
になってしまい、作業の形骸化が起こった。
という問題が事例ベースで報告されていますが、こう言った~
作業経験がある方は、想像に難くない内容かと思います。
***分析 [#b1730246]
-クラス・メソッド仕様書記述の意味合いも良く検討する。~
従来の手法は、設計に時間をかけて品質を出しているに過ぎな...
--具体的な事例に、1stepに対応する仕様書を書くという方法が...
--ただし、コレは、顧客予算が対応しなければ成立しない方法...
-IDEを使用してモジュールのスケルトンを作成し~
[[ドキュメンテーション・ツール]]でリバースするという方式...
--業務レベルの設計を行う人間にモジュール設計まで担当させ...
--雑にやっても、どの道、プログラム・レベルの設計で覆され...
***図表の利用 [#bf1f9a49]
イベントフロー、アクティビティ図(≒フローチャート)の事例
-問題
--ここまでのフォワード(モジュール・レベルの詳細設計書作...
イベントフロー、アクティビティ図(≒フローチャート)などか...
自動生成する位は考えないと、生産性が上がらないという意見...
--「一度 Word、Exel で設計していたプロジェクトにこれらを...
修正や設計に手間がかかる割には、製造・テスト工程の生産性...
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下...
-対策~
「ソースコードを自動生成する位は考えないと、生産性が上が...
--構造化言語というツールもあるが、仕様書は自然言語で記述...
(自然言語で問題ないため、ワザワザ他のツールを導入する動...
--UML(イベントフロー、アクティビティ図)などを納品物とし...
これら重複が「自然言語で書かれたドキュメント」と比較する...
---何を代替するのか?
---優れているか劣っているか?
-一部、業務アプリケーション開発の用途でも効果的なダイアグ...
--シーケンス図(アーキテクチャ説明、モジュール構成説明)
--状態遷移図(状態ごとの制御が複雑なプログラムの説明)
--ディシジョン・テーブル or ツリー(ディシジョンの説明)
-従って、上記の様な自然言語で表し難い仕様を説明する~
これらのダイアグラムを必要に応じて作成する場合は、~
補足説明書として付属させても形骸化は発生しません。
**リバースの事例 [#mafe6bac]
比較的多くの案件で採用されている。~
(業務的詳細設計書と方式設計書をコーディング工程で結合す...
モジュール・レベルの詳細設計書はリバース生成させる。
***問題 [#xd872266]
Doxygenを採用(A Hot Document等で代替も可能)し、~
メソッド内コメントのコメント規則を整備して~
設計書をリバース生成させる方式を導入したが定着せず。~
***分析 [#o7e4e5b2]
理由は以下
-イベント仕様書記述(業務的詳細設計書)で~
足りる(わざわざリバース生成する必要が無い)
-リエンジ用途(リエンジの詳細は後述)
--としては不完全である。
--として活用するのは先(将来)の話になってしまう。
-以下の様に、コメントの振り方が変わってきてしまう。
--以下がプログラム内に混在
---内部文書化目的のコメント(一般的なコメント)
---リバース生成目的のコメント
--このため、メソッド冒頭にメソッド仕様を纏めて記述するな...
製品など、納品やリエンジ用途ではなく自分のために使用する...
リバース生成方式の採用を本格的に検討しても良いかもしれま...
***納品用途 [#rd8e07ed]
モジュール・レベルの詳細設計書の納品を求められるケース
-必要不可欠というものではなく、作業形骸化を起こすため問題...
-前述の[[イベントフロー、アクティビティ図>#bf1f9a49]]で説...
>「修正や設計に手間がかかる割には、製造・テスト工程の生産...
むしろ、設計書の修正が追いつかずプロジェクトの完成度が下...
>という状態に陥ることになります。
-これでも、クラス・メソッド仕様書を納品物として求められる...
--リバース・ツールの生成する形式ではなくExcel形式で要求さ...
--手書きでフォワードしたもののみ認められる見積条件の場合...
***リエンジ用途 [#kd670643]
[[リエンジ用途でリバース・ツールを利用]]するのは、だいた...
*参考 [#z38ab040]
**Open 棟梁 Wiki [#c95dae93]
***[[ドキュメント標準のポイント>https://opentouryo.osscon...
----
Tags: [[:ドキュメンテーション]], [[:その他、開発の色々]]
ページ名: