「[[Open棟梁 wiki>https://opentouryo.osscons.jp]]」は、「[[Open棟梁Project>https://github.com/OpenTouryoProject/]]」,「[[OSSコンソーシアム .NET開発基盤部会>https://www.osscons.jp/dotNetDevelopmentInfrastructure/]]」によって運営されています。

-[[戻る>設計のポイント]]

*目次 [#xedebf30]
#contents

*概要 [#r9ec62d0]
ドキュメント標準のポイント

*ドキュメント標準化ワークフロー [#a20828be]
設計ドキュメントの標準化のためのワークフロー概要図

#ref(1.png,left,nowrap,１)

*[[ドキュメンテーション>https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3]] [#l9a517a1]

**[[設計書作成と作業形骸化>https://techinfoofmicrosofttech.osscons.jp/index.php?%E8%A8%AD%E8%A8%88%E6%9B%B8%E4%BD%9C%E6%88%90%E3%81%A8%E4%BD%9C%E6%A5%AD%E5%BD%A2%E9%AA%B8%E5%8C%96]] [#je628b67]
Windows Forms, Web Formsなど

-画面単位のモジュール化
-コンポーネントベース
-イベント・ドリブン

などを実現するフレームワークを活用する場合、詳細設計作業以降のモジュール設計作業の形骸化が発生することがある。~
（MVCなどの柔軟性の高いフレームワークを使用する場合、モジュール設計作業工程が重要になるケースもある。~
大規模開発でMVCが標準のJavaを使用するケースなどでは、モジュール設計書から、スケルトンの自動生成をしている事が多い。）

**[[ドキュメンテーション・ツール>https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%BB%E3%83%84%E3%83%BC%E3%83%AB]] [#w91b005c]
-納品、保守用のプロダクト
-マニュアル生成用のOSS
-ソースコード解析ツール

などは存在するが、

リエンジ用のドキュメント生成用途にはあまり適合しない。~
前述の「[[設計書作成と作業形骸化>#je628b67]]」の防止に利用できる。

*処理説明のリバース出力 [#i5ffaa0d]
-プログラム設計レベルのフローチャートでは、条件分岐数が多くなりすぎ、~
フローチャートを一見して、詳細設計内容を理解することは難しいと考える。

-このため、モジュールに詳細設計レベルの説明を付与するには、~
[[ドキュメンテーション・ツール>https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%BB%E3%83%84%E3%83%BC%E3%83%AB]]のメソッド中コメントを使用して、~
メソッド定義書の「処理説明」に詳細設計内容を出力すると良いと考える。

>※ メソッド中コメントが入っていないプログラムでは~
メソッド定義書の「処理説明」欄に詳細設計内容を出力できないので注意する。

**A HotDocument [#x795f6cb]
-A HotDocumentのメソッド中コメントのコメント ルールは単純で、~
コメントを「///」で開始することでメソッド中コメントを記述でき、~
コメント文字「/」を１つ増やすことによって字下げが可能になっている。

-メソッド中コメント記述の際は、メソッド定義書に出力される~
「処理説明」の見易さなどを意識する必要がある。

#ref(2-1.png,left,nowrap,２-１)

***サンプル プログラム [#b4ecd2e5]
#ref(2-2.png,left,nowrap,２-２)

***Excel出力例 [#w44967bc]
#ref(2-3.png,left,nowrap,２-３)

***HTML、ヘルプ ファイル出力例 [#mf86a168]
#ref(2-4.png,left,nowrap,２-４)

***参考 [#j338eb56]
-ドキュメンテーション・ツール - マイクロソフト系技術情報 Wiki~
https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%BB%E3%83%84%E3%83%BC%E3%83%AB

**Doxygen [#b743524f]
-/*! ～コメント～ */を使用すれば、メソッド定義書に出力できる。

-字下げは、HTML コマンド機能 を使用して代替できる。
--Doxygen > HTML コマンド~
http://www.doxygen.jp/htmlcmds.html

-ただし、A HotDocumentと同様にメソッド中コメント記述の際は、~
メソッド定義書に出力される「処理説明」の見易さなどを意識する必要がある。

***出力例 [#w44967bc]
#ref(2-5.png,left,nowrap,２-５)

***参考 [#ga3ed4b0]
-ドキュメンテーション・ツール - マイクロソフト系技術情報 Wiki~
https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%BB%E3%83%84%E3%83%BC%E3%83%AB

**進捗の管理方法 [#a991f955]

-[[設計書作成と作業形骸化>#je628b67]]で説明したような理由で、詳細設計作業以降の~
モジュール設計作業工程の成果物を作成しない場合、モジュール設計作業工程の進捗管理が困難になる。

-このため、モジュール設計作業工程で、[[ドキュメンテーション・ツール>https://techinfoofmicrosofttech.osscons.jp/index.php?%E3%83%89%E3%82%AD%E3%83%A5%E3%83%A1%E3%83%B3%E3%83%86%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%83%BB%E3%83%84%E3%83%BC%E3%83%AB]]を使用し、~
[[処理説明のリバース出力>#i5ffaa0d]]をさせれば、これをモジュール設計作業工程の進捗報告の元情報として代用できる。

#ref(3.png,left,nowrap,３)

*参考 [#qa9b9eec]

**OSSコンソーシアム [#mab417f1]
-ドキュメント標準化ってどこまで効果あるのか？（生産技術ネタ~
https://www.osscons.jp/jo0jixmdl-537/

**Think IT（シンクイット） [#t28ffb58]

***即活用！業務システムの開発ドキュメント標準化 [#de5795dc]
記事一覧~
https://thinkit.co.jp/series/6536

-第1回 開発ドキュメント体系と業務フロー~
https://thinkit.co.jp/free/project/4/1/1
-第2回 機能一覧表とI/O関連図~
https://thinkit.co.jp/free/project/4/2/1.html
-第3回 基本設計書~
https://thinkit.co.jp/free/project/4/3/1.html
-第4回 詳細設計書（前半）~
https://thinkit.co.jp/free/project/4/4/1.html
-第5回 詳細設計書（後半）~
https://thinkit.co.jp/free/project/4/5/1.html
-第6回 単体テスト仕様書＆報告書~
https://thinkit.co.jp/free/project/4/6/1.html
-第7回 結合テストと総合テスト~
https://thinkit.co.jp/free/project/4/7/1.html
-第8回 要求仕様書の標準化プロセス~
https://thinkit.co.jp/free/project/4/8/1.html

***令和時代のシステム開発では、どのような設計書を書くべきか [#xf8b32a8]
記事一覧~
https://thinkit.co.jp/series/9344

-第1回 今、システム開発の実態はどうなっているのか~
https://thinkit.co.jp/article/16984
-第2回 システム開発で作成するドキュメントの体系~
https://thinkit.co.jp/article/17064
-第3回 我々は、なぜ設計書を作成するのか~
https://thinkit.co.jp/article/17166
-第4回 システム開発で必要とされるドキュメントフロー~
https://thinkit.co.jp/article/17194

**変わらない開発現場 [#xb53411e]

-とあるコンサルタントのつぶやき > 『変わらない開発現場』シリーズ 情報ポインタ一覧~
https://blogs.msdn.microsoft.com/nakama/2017/06/17/sier-modernization/
--CLT-016_拝啓 『変わらない開発現場』を嘆く皆様へ~
～エンプラ系 SI 開発現場の「今」を変えていくために～~
https://www.slideshare.net/decode2016/clt016-si
--[DO08] 『変わらない開発現場』を変えていくために~
～エンプラ系レガシー SIer のための DevOps 再入門～~
https://www.slideshare.net/decode2017/do08-sier-devops
--拝啓『変わらない開発現場』を嘆く皆様へ~
～変わっていくエンタープライズ系業務システム開発とマイクロソフトエンタープライズサービスの取り組み～~
https://blogs.msdn.microsoft.com/nakama/2017/05/25/devmodernization/
トップ   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS