skillup

技術ブログ

ドキュメント作成 プロジェクト管理

開発時最低限必要かつ有用なドキュメントに関して

投稿日:2021年7月17日 更新日:

ウォーターフォール型の開発をかれこれ1年近くやっております。

自分がやってきた仕事とすると別職種に近いようなイメージでしたが、得ることも多かったため、ここに記しておこうと思います。

以前書いたことの記事に近いかなあ・・・

使える設計書作成に関して

ドキュメントのメリット

まあ、これ自体が納品物になるのが現実的にはあるのですが、実開発作業での最大のメリットは

仕様の認識の統一、作業の分業化

が一番大きいかと思っております。

今までの自分がやってきた現場はこれ作ってくださいみたいなお客さんに見せるレベルのパワポからプロダクトを作ることが多かったのですが、これだと仕様の認識に齟齬があった時はもちろん、何より分業ができないという大きなデメリットがあります。

準委任でやってる場合は問題にならないと思いますが、請負の場合はそもそも仕様が明確になっていないと相手側が見積もりが正確に出せない。仕様変更なのかバグなのかの境界が明瞭にならずトラブルになる。

特に設計をしないプログラマ(世間的には設計をしないのがプログラマのようですが・・・・)に仕事を任せることができるのが大きいですね・・・

ドキュメントがあることで仕様の認識を統一でき、作業の分業が可能になるのが一番メリットとして大きいかなあと思っております。

作る際のポイント

情報の同期を意識する

あるあるパターンなのがドキュメントの状態が古くなってしまって、コードとドキュメントのどちらが正なのかがわからなくなってしまっているという状態です。なるべくコードとの修正をセットにする、理想論を言えばマークダウンで作り、コードレビュー時にコードとセットで付与し、修正がなければマージしない・・・というのがベストでしょう。

Excelを使う場合は、マクロなどが利用できて、情報の同期ができるようにしておくのがポイントかと思います。テーブル設計だと定義書とDDLがセットになっていることやマイグレーション管理などができると理想でしょう。

出来るだけ少ない量にする

同じ情報を書く場所が多くなると、情報の差分がどうしてもできてしまうことが多いです。例えばパラメータを機能設計書とAPI仕様書にかくとその分差分量が増えてしまうので、出来るだけ作る量、ドキュメントを少なくなるようにしましょう。

チェックポイントをあらかじめ決めておく

レビュー時に指摘ポイントがコロコロ変わってしまうことなどがあることも多いです。そのため、統一したなるべく少ないチェックポイントでレビューするのが良いでしょう。

フォーマットを決めて、入力欄を出来るだけ少なくする

品質の統一という点から入力欄を出来るだけ少なくすることでばらつきを抑えることができるかと思います。このようにすることでドキュメントの統一を取れるようにするのが理想かと思います。

必要だと思うドキュメント

これ自体が納品対象になるとかはおいておいて開発時に必要なものとして、以下を考えてみました。

  • テーブル定義書、ER図
  • 機能設計書(テーブルとプログラムの処理フローが最低限わかるもの。シーケンス図がベスト?)
  • テストデータ書、テスト仕様書
  • API仕様書(機能設計書と同期できるタイプのもの)

他に設定ファイルなどに入れたり、そこから起こせるものとしては

  • システム設定値関連
  • ログ設計書
  • メッセージ仕様書

などですかね。これらはできればExcelで作るにしても、マクロで設定ファイルが自動作成できて、そこから情報を同期できるようにしておくのがベストだと思います。

あとは画面遷移図とかですかね・・・これまで自分が担当してこなかったんですが、サクッと作ることができればあったほうがいいと思いますね。

-ドキュメント作成, プロジェクト管理
-,

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

no image

手動テストと自動テストのメリデメについて

自動テスト環境で作業をするようになって1年近く経ちますが、現在の案件でも手動テストはやっております。 一般的には自動テストをがっちりと装備するのがいいと言われがちですが、やはり自動テストのデメリット、 …

no image

プロジェクトごとのフェーズでやっておいたほうが良いと思うこと

またプロジェクトの途中ではありますが、自分の中で要件定義〜外部結合の始まりまでのフェーズを経験して思ったことなど Contents1 全般2 要件定義3 基本設計4 詳細設計5 製造6 単体テスト〜内 …

no image

採用の重要性と一般的な採用の問題点について

私自身は現時点では経営者でも人事でもないのですが、学習塾運営スタッフ時代から講師の採用は少ししていたのと、以前の会社でも規模が小さいということもあり、多少関わらせていただきました。 そこで思ったことを …

no image

ファジープロジェクト対策 その2

前回に引き続き、大事だと思ったこと。一部単なるフレームワークの作り方的な内容になっているかも。 Contents1 テンプレート共通化2 バリデーション3 ログ出し4 異常系の処理5 新規プラグイン+ …

no image

コミュニケーション能力の定義

新卒でも既卒でも採用基準で非常に大きい要素といえばコミュニケーション能力かと思います。 が、この言葉、明確な定義がなく、私もいろんな会社でいろんな人と仕事をしてきましたが、明確な言語化がはっきりとでき …

アーカイブ