「Open棟梁 wiki」は、「Open棟梁Project」,「OSSコンソーシアム .NET開発基盤部会」によって運営されています。
目次 †
概要 †
ドキュメント標準のポイント
ドキュメント †
標準化ワークフロー †
設計ドキュメントの標準化のためのワークフロー概要図
画面定義書-画面項目定義 †
項目移送処理産業の中で最も重要な「画面定義書-画面項目定義」のサンプル。
画面定義書-画面項目定義サンプル.xls
Windows Forms, Web Formsなど
- 画面単位のモジュール化
- コンポーネントベース
- イベント・ドリブン
などを実現するフレームワークを活用する場合、詳細設計作業以降のモジュール設計作業の形骸化が発生することがある。
(MVCなどの柔軟性の高いフレームワークを使用する場合、モジュール設計作業工程が重要になるケースもある。
大規模開発でMVCが標準のJavaを使用するケースなどでは、モジュール設計書から、スケルトンの自動生成をしている事が多い。)
- 納品、保守用のプロダクト
- マニュアル生成用のOSS
- ソースコード解析ツール
などは存在するが、
リエンジ用のドキュメント生成用途にはあまり適合しない。
前述の「設計書作成と作業形骸化」の防止に利用できる。
処理説明のリバース出力 †
- プログラム設計レベルのフローチャートでは、条件分岐数が多くなりすぎ、
フローチャートを一見して、詳細設計内容を理解することは難しいと考える。
- このため、モジュールに詳細設計レベルの説明を付与するには、
ドキュメンテーション・ツールのメソッド中コメントを使用して、
メソッド定義書の「処理説明」に詳細設計内容を出力すると良いと考える。
※ メソッド中コメントが入っていないプログラムでは
メソッド定義書の「処理説明」欄に詳細設計内容を出力できないので注意する。
A HotDocument? †
- A HotDocument?のメソッド中コメントのコメント ルールは単純で、
コメントを「///」で開始することでメソッド中コメントを記述でき、
コメント文字「/」を1つ増やすことによって字下げが可能になっている。
- メソッド中コメント記述の際は、メソッド定義書に出力される
「処理説明」の見易さなどを意識する必要がある。
サンプル プログラム †
Excel出力例 †
HTML、ヘルプ ファイル出力例 †
参考 †
Doxygen †
- /*! ~コメント~ */を使用すれば、メソッド定義書に出力できる。
- 字下げは、HTML コマンド機能 を使用して代替できる。
- ただし、A HotDocument?と同様にメソッド中コメント記述の際は、
メソッド定義書に出力される「処理説明」の見易さなどを意識する必要がある。
出力例 †
参考 †
進捗の管理方法 †
- 設計書作成と作業形骸化で説明したような理由で、詳細設計作業以降の
モジュール設計作業工程の成果物を作成しない場合、モジュール設計作業工程の進捗管理が困難になる。
参考 †
OSSコンソーシアム †
Think IT(シンクイット) †
即活用!業務システムの開発ドキュメント標準化 †
記事一覧
https://thinkit.co.jp/series/6536
令和時代のシステム開発では、どのような設計書を書くべきか †
記事一覧
https://thinkit.co.jp/series/9344
日経 xTECH(クロステック) †
読み手が納得する開発ドキュメントの作り方 †
https://tech.nikkeibp.co.jp/atcl/nxt/column/18/01054/
「要件は現行通り」と言われ困惑、ドキュメントが無いIT職場の悲惨な現状 †
https://tech.nikkeibp.co.jp/atcl/nxt/column/18/00205/012000026/
変わらない開発現場 †