ソフトウェア設計ドキュメントを書くことが重要な理由

おめでとうございます、あなたは有能な独立した開発者です。 おそらくテスターとして働いていたあなたの謙虚な始まりから、あなたはチーム開発者、次に上級開発者に進み、そして今、あなたはクライアントと直接働くことへの別の飛躍、それらすべての中で最大のものを作りました。

しかし、他の遷移が線形であった場合、この最後の遷移は指数関数的でした。 以前は、クライアントと協力していた、またはそれ自体がソフトウェアビジネスに携わっていた雇用主から行進命令を受け取りましたが、今では、専門家のテストやプログラム管理などにかつて分散されていたすべての責任はすべてあなたのものです。 そして今、あなたはソフトウェアビジネスに携わっていないクライアントと仕事をしています。 彼らはソフトウェアを必要とする別のビジネスに従事しており、彼らがあなたに何を求めているかについて明確で正確なビジョンを持っていません。 これは、見た目よりもはるかに大きな課題です。

*注：*ここでは、開発者に1人の軍隊を求めている小規模なクライアントについて説明します。 フリーランサーがたどることができるルートはこれだけではありません。Toptalで一緒に仕事をしているクライアントはそれだけではありませんが、私が最も楽しんでいるルートです。 もちろん、自分ではなくチームで作業している場合は、以下の一部は適用されません。 たとえば、アジャイル手法やスクラムを使用している場合は、マイルストーンの構造を少し変えたいと思うでしょう。

あなたは皆、コミュニケーションの最高の重要性について聞いたことがあります。 Skypeで簡潔な説明を数文取得し、 「完了したら3か月後に会いましょう」と言っても作業できません。 クライアントがワイヤーフレームと詳細な機能仕様を送信することはめったにないため、クライアントと連絡を取り合う必要があり、作業のすべての段階で、目的について一致するアイデアがあることを確認してください。 あなたは、ソフトウェアが何をすることになっているのか、どのように見えるのか、そして流れるのかについての非常に一般的な考えを得るでしょう。 普段始めている大雑把な説明に基づいてアプリケーションを作成する場合、クライアントがその結果に満足する可能性はほとんどありません。 各段階で、合意に近づくまでの道のりを繰り返す必要があります。

チームの全員が同じ文化、同じ母国語を話し、同じ廊下で働き、毎日会うなど、ソフトウェアビジネスに携わっている企業で何年も働いてきたことは注目に値します。会社はまだ半分の時間で欲しいものを手に入れませんでした。 間違いありません。ここでの課題は非常に大きいです。

ソフトウェア設計ドキュメントが重要である理由

したがって、新しいプロジェクトに着手するときは、 XcodeまたはVisual Studioを開く前に、明確で合意された設計目標を設定する必要があります。 そして、これらの目標は仕様書で確立する必要があります。 クライアントが作成していない場合は、IDEを開く前に、作成してレビューのために送信する必要があります。 そして、「設計図書の時間がない」というクライアントに率直に出会ったら、先に問題があるので、プロジェクトから離れるべきです。 仕様は特に長くする必要はありません。 ほんの数ページでもかまいませんが、少なくとも、ユーザーインターフェイスをレイアウトし、ワイヤーフレーム（UIコンポーネントがある場合）を含め、完了のマイルストーンを設定する必要があります。

この文書がないと、クライアントはあなたに言ったことやあなたが言ったことに異議を唱え、以前のコミュニケーションのカットアンドペーストを怒って送信し、クライアントが要求する時が来るまで解釈して議論するという、厳しい不満のループに陥ります。アプリケーションを「彼らが実際に求めていたもの」に準拠させるために変更を加え、それらの変更を無料で行うことを期待していること。

このソフトウェア設計ドキュメントを使用すると、そのような問題に対する答えが得られます。不一致が生じた場合は、クライアントが同意してサインオフした仕様を参照し、レターにそれを満たしていることを指摘できます。 怒りの議論の代わりに、あなたは文書に修正と明確化をします。 どちらかといえば、クライアントは、そもそも不正確さをすり抜けさせてしまったことをお詫びします。

私たちは皆、満足したクライアントを望んでいます。 私たちは皆、友好的な協力関係を望んでいます。 そして、私たちは皆、よくやった仕事の誇りを望んでいます。 しかし、実際の仕事が何であるかについて曖昧さがあれば、これらは達成できません。 クライアントが設計ドキュメントが余計な作業であると言った場合、何らかの誤解のために修正が必要になったときに実際の余計な作業が発生することをクライアントに説明するのはあなたの仕事です。 それでもクライアントがあなたがそのような文書なしで前進することを主張するならば、あなたはあなたが実行不可能な関係を持っているという事実を受け入れて立ち去るべきです。

ソフトウェア設計仕様は実際に何を指定する必要がありますか？

少なくとも、目的のアプリケーション、完了の基準、およびマイルストーンの説明である必要があります。 実装仕様ではなく、要件および機能ドキュメントとして最もよく説明されているものを共有していることを忘れないでください。 そして、特定の実装が明確なクライアントの目的でない限り、それをどのように機能させるかはあなた次第です。

ユーザーインターフェース

ほとんどのプロジェクトはアプリケーションであり、ライブラリやフレームワークではありません。 しかし、これらのいずれかを成果物として持っている場合は、ユーザーインターフェイスが設計ドキュメントテンプレートの最も問題のあるコンポーネントであり、ほとんどの場合誤解を招く可能性があるため、幸運を祈ってください。 多くのクライアントから、プログラマーではないグラフィックデザイナーがグラフィックエディターで作成した完璧なイラストが送られてきます。 しかし、問題は次のとおりです。これらの図は、アニメーション、制御状態（たとえば、このボタンは無効になっていますか？使用できない場合は消えますか？）、またはボタンが押されたときに実行するアクションについては何も述べていません。

これらの図の背後にあるコードを書き始める前に、これらの質問すべてに答えることができるはずです。 具体的には、次のことを知っておく必要があります。

1. コントロールは常に表示および/または有効になっていますか？ それらの状態はどのような条件下で変化しますか？
2. ビットマップのように見えます—それはボタンですか？
3. これらの状態とビューの間でどのような遷移が発生しますか？ そして、それらはどのようにアニメーション化されるべきですか？

クライアントの同意のためにUIを生成するのはあなた次第である場合は、逆に同じことを行います。ワイヤーフレームツールを使用して、ビューがさまざまなアプリケーション状態で表示するバリアントを含む、画面レイアウトの完全なセットを作成します。 これは徹底的で退屈な作業になる可能性がありますが、後悔することはありません。大きな影響を伴う小さな誤解により、大量のコードを書き直したり、インターフェイスを再作成したりする必要がなくなります。 デュアルアプリケーションを作成する場合（たとえば、iPhoneとiPadの両方）、両方に別々のワイヤーフレームを作成します。

画面のサイズも重要です。 （執筆時点で）iPhone画面には3つのサイズがあります。 3.5インチと4インチの画面用に別々のワイヤーフレームはおそらく過剰ですが、それらを作成する必要があるかもしれません。 ほとんどの場合、比率を変更するだけです。

クライアントからグラフィックが提供されている場合は、適切なアスペクト比で適切なサイズになっていることを確認してください。 テキストまたはオブジェクト（円など）を含むビットマップをモーフィングすると、歪みが発生します。 それらが一致しない場合は、一致するサイズでそれらを再作成するようにクライアントに指示します。 3.5インチのスプラッシュスクリーンを4インチのスプラッシュに伸ばして、それと一緒に転がすことができると思い込まないでください。

機能性

アプリケーション設計ドキュメントで尋ねる重要な質問：

• アプリケーションは何をしますか、そしてそれはどれくらい速くそれをしますか？
• 考えられる障害状態とその処理方法を教えてください。
• 最初の実行時（つまり、インストール後）に実行される1回限りの操作は何ですか？
• ユーザーが任意の種類のエントリ（ブックマークなど）を作成する場合、制限は何ですか？

ここでのエラーや誤解はコードの書き換えを意味するため、これらのアイデアを一般化し、できる限り詳細かつ徹底的に説明してください。

マイルストーン

仕様テンプレートは、明確なマイルストーンをレイアウトする必要があります。 クライアントが機能およびユーザーインターフェイスの設計を作成する場合は、その後、一連のマイルストーンについて合意する必要があります。 これらは請求のしきい値でもある場合がありますが、少なくとも、完了に向けた明確な指標を提供します。 マイルストーンは、機能および/またはコンポーネントの観点からのものである可能性があります。 ギグに一連の成果物が含まれる場合は、個別のアプリケーションである場合もあります。 可能であれば、マイルストーンの期間はほぼ等しくする必要があります。

ソフトウェア設計仕様例

ここでは、適切な設計ドキュメントの構造例をレイアウトします。 もちろん、このテンプレートは必要に応じて調整する必要があります。 別の例については、この記事に基づいたJoelSpolskyのサンプル仕様を参照してください。 彼はドキュメントへのアプローチが少し異なりますが、同様の感情を共有しています。

目標のステートメント

プロジェクトとその対象読者を説明する短い段落を含めます。

機能説明

アプリケーションは何をしますか？ ユーザーはどのようなアプリケーション状態（コアユーザーシナリオの高レベルの説明）に遭遇しますか？

たとえば、機能の説明は次のようになります。

• ファーストラン
• 新しい_____の作成（ゲーム、検索など）
• 操作
• 背景と前景の動作

ユーザーインターフェース

各ページのワイヤーフレームを、次の詳細な説明とともに含めます。

• 状態（有効/無効/強調表示）および操作を含む各コントロール。
• サポートされている方向とそれらの間の遷移。
• 表現された機能。
• エラー処理。
• 寸法と制約。

これが私の最新のiOSアプリであるNotifEyeに関連するワイヤーフレームです。

興味があれば、Balsamiqのワイヤーフレーミングツールを使用してこれらのモックアップを作成しました。

たとえば、UIの説明は次のようになります。

• ナビゲーションバー
  • 左ナビゲーションコントロール：ホームページに戻る
  • タイトルバー：現在の画面または操作名
  • 新しいボタン：新しいものを作成します
• テーブルビュー
  • セクション0：セクションタイトル
  • セクション0行：
    • 行制御0（例：画像）
    • テキスト行0
    • テキスト行2

マイルストーン

上記のように、完了の期限と予想される成果物。

たとえば、デザインドキュメントテンプレートのマイルストーンセクションは次のようになります。

1. 画面を表示し、一時的なトランジションとサンプル画像/テキストを含むファサードアプリケーション
2. 通信プロトコル：アプリケーションはネットワーク/サーバーに接続します
3. 機能的なマイルストーン1：…
4. アルファアプリケーション（全機能付き）
5. 安定
6. リリース

ソフトウェアドキュメンテーションの関連性を維持する

あなたとあなたのクライアントが仕様書に同意した後、設計段階が終了したことを意味するものではありません。 どちらも考慮していなかった詳細が常にあり、中間結果を見ている間、新しいアイデア、設計変更、予期しない設計上の欠陥、および実行不可能な提案に遭遇します。

デザインは進化し​​、変更はドキュメントにキャプチャする必要があります。 私の25年間の経験では、これが起こらなかったプロジェクトに一度も取り組んだことはありません。これには、自分のアプリケーション（つまり、自分が自分のクライアントだった場合）が含まれます。 それでも、詳細な仕様書を作成し、必要に応じて調整しました。

何よりも、連絡を取り合いましょう。 少なくとも週に数回、クライアントに連絡し、進捗状況を報告し、説明を求め、同じビジョンを共有していることを確認してください。 あなたのコミュニケーションのリトマス試験として、あなたとあなたのクライアントがこれらの3つの質問に同じ答えを与えることを確認してください：

1. 開発者は何に取り組んでいましたか？
2. 開発者は現在何に取り組んでいますか？
3. 開発者は次に何に取り組みますか？