質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

89.07%

設計書の記載内容について

解決済

回答 1

投稿

  • 評価
  • クリップ 4
  • VIEW 4,273

ts.tubasa

score 123

いつもお世話になっております。

システム開発を行う中で、アジャイル開発を行い、最終的に基本設計書を起こしています。
開発サイクルが早いため、詳細設計書まで書ききれていません。

一度、開発プロセスを見直し、詳細設計書を記載したいと考えています。

APIを開発しAPI設計書は作成しているのですが、
APIの内部設計までは制作できておりません。
私の会社では、サーバーサイドの開発とクライアントサイドの開発が、
遠距離で別れているため、シーケンス図、API設計書、画面設計書が
どうしても中心になってしまっております。

ソース上にコメントを残しているのですが、それでも、これじゃまずいとおもい現在に至ります。

テーブル設計書しかり、ドキュメントが追いついて来ない場合が多々あります。
それがその状況であまり必要でないため、後回しになってしまっているためだと思いますが、
ドキュメントを起こす手間が否めません。これを見直すために、開発プロセスを見直すのですが、
ドキュメント作成に手間がかかりすぎて、開発があまりにも遅くなるのもどうかと思ってしまいます…。

皆様にご教授頂きたいのですが、

  1. APIの内部設計書の内容・精度
  2. 設計書のドキュメントのおすすめ
    (私は、Excelと、WebサービスのCacooなどを利用していますが、Excelの内容が悪いのか手間です)

上記、2点をご教授いただけないでしょうか。

よろしくお願い致します。

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 過去に投稿した質問と同じ内容の質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 1

checkベストアンサー

+1

そもそもなぜ詳細設計書を作成したいと思うようになったんですか?
シーケンス図、API設計書、画面設計書が揃っているのであれば、実装はできると思います。

僕が詳細設計が必要だと思う時はバッチ処理ですね。
画面は画面設計書があれば何となくイメージつきますが、
バッチは概要説明とある程度の処理内容を記載しないとプログラマに意図が伝わりにくいです。

画面設計書の粒度にもよりますが、僕は大まかに以下の情報はあるべきだと思っています。

  • 画面のURL(実装者に自由に決めさせるのは好みじゃありません)
  • 画面項目の説明(カンマ区切り、yyyy/MM/dd、少数第二位で四捨五入、初期値など)
  • 基本的な入力チェック(必須、桁数、正規表現など)
  • 業務的なチェック(パスワード変更が2ヶ月行われてなければ、パスワード変更を促すなど)
  • 一覧表示があるのであれば、初期の並び順
  • 画面項目とDBのマッピング(取得も登録・更新も)
  • 画面に表示する全てのメッセージの内容(ここも実装者に決めさせるのは好みじゃありません)
  • 全てのリンクやボタンの説明(どのテーブルに登録して、どこに遷移するぐらいのレベル)

APIの内部設計書の内容・精度

  • 1回の処理で複数通信するのであればフローが分かるもの(アクセストークンを取得してからなど)
  • INとOUT(コード系は全てのコードの説明も。例えば処理結果の「成功」や「失敗」など)
  • URL
  • RESTであればHTTPメソッド
  • APIの結果毎の振る舞いは、画面設計書やバッチ設計書に書く(呼び出し元)

設計書のドキュメントのおすすめ 

結局は僕もExcelで書いてます。

  • みんな慣れている
  • お客様の環境にもだいたいOfficeの環境はある(PDFで渡すかもしれませんが)
  • マクロで自動化などもできる
    画面ワイヤーはCacooなどを使った方がいいかもしれませんね。
    Excelで画面のイメージを書くのは中々面倒くさいですし。
    Excelは表計算ソフトなので、ドキュメント作成の否定派は多いですが、
    生産性は結局ツールの「慣れ」が占める割合が大きいのと、
    ある程度誰でも使えるものという基準でいいと思います。
    しょせんはドキュメントです。

投稿

編集

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2017/02/21 16:49

    ご回答ありがとうございます。

    > 詳細設計書を作成したいと思うようになったんですか?

    詳細設計書がほしいと思った理由としましては、API仕様書を書いていた際に、
    内部処理のイメージが付きづらいため、作成しようと思いました。

    > 僕が詳細設計が必要だと思う時はバッチ処理ですね

    この理由に近い気がします。

    > 生産性は結局ツールの「慣れ」が占める割合が大きい

    おっしゃる通りだと思います。
    慣れてくるともう少し効率化できないか、ついつい考えてしまいました。

    画面仕様書の精度のご教授ありがとうございました。

    キャンセル

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 89.07%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

関連した質問

同じタグがついた質問を見る