設計文書には、特定の設計に対する賛否両論の議論を含めるべきですか、それとも事実と理論的根拠に焦点を当てるべきですか？

私は現在、設計ドキュメントを更新して、将来の開発者向けに正しく最新のものにするためのプロセスを進めています。

現在、ドキュメントは事実のみに焦点を当てており、設計がどのようになっているかを示しています。提示された決定の根拠はありません。理論的根拠を把握することが重要だと思います。そうすることで、開発者は何かがそうである理由を知ることができます。すべての設計上の決定、特にプロジェクトに取りかかる前に下した決定に関するすべての理論的根拠を追加することはできませんが、この部門でできることをやっています。

ただし、いくつかの設計上の決定は、プロジェクトの要件を考えると、敬意を表して非常に貧弱な決定です。ただし、良いものもいくつかあります。

私の最初の考えは、将来のメンテナーの注意を集めるために、設計上の問題と潜在的な解決策またはこれらの問題の回避策についての議論を含めるべきだということでしたが、設計文書がこの種の議論と情報の場所であるかどうかはわかりません。他の人がこのシステムで作業し、ドキュメントを更新するので、デザインの「批評」が「このデザインを新しいものに引き裂く」ように雪だるまして欲しくありません。これは明らかに不適切です。

私のマネージャーがどちらの決定も支持するので、それは私次第です。私が取るアプローチに関係なく、作成されたドキュメントは公式にバージョン管理され、通常は開発作業を任される前にシステムで作業する開発者に提供されます。新しい開発者は、開発作業を開始する前に、特定のソフトウェアシステムに関連するドキュメントに慣れることが期待されています。

質問：

• 設計文書が未加工の事実（「これが設計」）と論理的根拠（「これが設計である理由」）に固執するか、設計上の問題となる可能性のある欠陥のない問題を指摘するために使用されるべきか将来の開発者？
• 設計ドキュメントを使用してこの情報をキャプチャする必要がない場合、どのタイプのドキュメントでそれをキャプチャする必要があり、その他は設計合理性、トレードオフ、および既知の問題（欠陥ではないため、欠陥を追跡するための議論）でキャプチャする必要があります他のツールを使用していますか？）

長所と短所を1つまたは2つの文にまとめることができる場合は、設計文書に入れてもかまいません。長いものはすべて分離する必要があります。

私が現在働いているところでは、通常、すべての重要な決定と重要な決定を追跡するための別個の「設計決定」文書があります。多くの場合、問題を説明する段落（「各処理サイクルの終わりに一部のファイルをサーバーから特定のユーザーに移動する必要があります。これを行うには多くの方法があります...」）、ソリューションの説明」（「FTP経由でファイルを移動する」など）、「長所」（「管理がユーザーにとって簡単」など）、「cons」（「ABC-XYZコンプライアンスに十分に安全ではない」など）、特定の決定が選択された理由を説明します（「FTPは特定のコンプライアンス要件を満たすことができないため、FTPは使用されません」など）。設計文書は通常、選択した決定のみを参照しますが、

設計文書が未加工の事実（「これが設計」）と論理的根拠（「これが設計である理由」）に固執するか、設計上の問題となる可能性のある欠陥のない問題を指摘するために使用されるべきか将来の開発者？

「どちらでもない」ではありません。

そもそもドキュメントを読む人はいません。彼らはスキム-せいぜい。したがって、できるだけ少ないドキュメントを書きます。1つのドキュメントは、誰もが忍耐を持っているすべてです。「その他の問題」を含む2番目の「非設計」ドキュメントは、まったく読まれそうにありません。

1つのドキュメントの利点は？人々はそれを読むかもしれません。

1つのドキュメントの短所は？少ない。ほとんどが古くなっています。

複数のドキュメントの利点？なし。

複数のドキュメントの欠点？DRYの原則とリテラシープログラミングについて読んでください。複数のドキュメントは、エラーの複数の原因を意味します。各ドキュメントは互いに同意せず、コードにも同意しません。これはかなり明白です。これが狂気の道です。

手巻きを避けてください。

賛否両論のドキュメントは、what-ifおよび魅力的な迷惑な議論の不明確な深さに引きずり込まれる可能性があります。

長所と短所を提示する必要があると感じた場合は、短く、要点を示してください。

何に焦点を当てます。

裸の骨にまで及んでいないものを保管してください。

ベンチマーク、研究、または実際に代替案を検討したことがある場合は、それを文書化します。ただし、代替案を検討している場合は、最小化します。

これは、試練と苦難のあなたの個人的な歴史であってはなりません。

• 問題がありましたか？修正した？数週間かかった？本当に苦労した？かろうじて興味深い逸話。コードで修正されています。以前のバージョン、間違ったバージョン、バグのあるバージョン、低パフォーマンスのバージョンは関係ありません。彼らはせいぜいブログフィードです。

• まだ問題がありますか？未修理？それは代替手段があることを意味します。これを文書化します。

意思決定のプロセスには3つの重要な事実があります。

• 試行されたが動作しなかったもの（および移動するターゲットをターゲットにしているために動作しなかった理由）
• とは
• （Xが実装されるのを待っているだけです...）

ただし、 "What is"を除き、他のすべてのユーザーは読者を混乱させ、読者がシステムを悪用するのを防ぎます。

他の2つをキャプチャするというアイデアは気に入っていますが、システムの学習にはあまり興味がありませんが、システムを変更すると時間を節約できます。

したがって、@ FrustratedWithFormsDesignerを公開するという考えにひねりを加えて構築します。独自のライフサイクルでさらに別のドキュメントを作成する代わりに、付録セクションを追加します。次に、議論に値する各決定について、附属書の関連エントリを指し示します。

はい。設計文書は、記述されている設計に関連する利点、リスク、および仮定を説明する必要があります。設計文書にはいくつかの目的があります。

1. デザインを書き留めて、誰もが理解できるようにし、各人の理解が時間の経過とともにドリフトしないようにします。

2. プロジェクトで作業している非技術者に設計を伝えます。

3. スケジューリング、リソース割り当て、コスト見積もり、およびその他の種類の計画を支援します。

4. プロジェクト全体のドキュメントの重要な部分になります。進行中のプロジェクトに参加するとき、または完了したプロジェクトを維持する必要があるとき、よく書かれた設計文書があれば、人生はずっと楽になります。

5. 多くの場合、契約で必要な成果物の1つです。

（おそらく他にもありますが、これらは良い出発点です。）

これらの目的のすべては、この設計が選択された理由と関連するリスクが何であるかを明確に説明する設計ドキュメントによってうまく機能します。

1. チームの全員がリスクと利点を理解し、それらが連携してそれらのリスクを回避し、設計の利点を最大限に活用できるようにすることが不可欠です。

2. 技術者以外のチームメンバにとっては、多くの場合、設計自体の詳細よりもリスクと利点を理解することが重要です。

3. リスク管理は、プロジェクトマネージャーが成功を確実にするためにできる最も重要なことの1つであり、最初のステップは、管理する必要があるリスクを識別することです。リスクへの対処方法を決定するのはマネージャー次第ですが、設計の既知のリスクを指摘するのは設計者の責任です。

4. リスクが問題ではなくなった場合でも、設計が作成された時点の状況を説明するのに役立つため、文書化しておくと便利な場合がよくあります。それでメンテナーは次のようなことを決めることができます：「さて、彼らはこの方法でそれをやりました。しかし、それはもはや問題ではないので、そのコードをよりシンプルで高速な実装に置き換えることができます。」もちろん、利益にも同じことが言えます。

5. クライアントのプロジェクトに取り組んでいる場合、リスクとメリットを文書化することが特に重要です。これにより、クライアントは特定の状況下で問題が発生する可能性があること、または設計の変更を要求すると約束された利点の一部が危険にさらされることに気付くことができます。

すでに実装されているシステムの既存の設計ドキュメントを使用しているという質問から収集します。その場合、起こりうるリスクの多くはもはやリスクではないため、事後にそれらを文書化することはあまり意味がありません。ただし、元のデザインでうまく機能しなかった部分を見ることができるため、後知恵の利点があります。次のいずれかを行う必要があると思います。現在の問題領域を特定し、解決策（関連するリスクを含む！）を提案する別のセクションを追加します。または、同じことを行う別のドキュメントを作成します。この新しいセクション/ドキュメントは、ソフトウェアの次のバージョンの設計ドキュメントに発展する可能性があります。

役立つと思われるデザインドキュメントの作成に関するブログエントリを次に示します。

より明白なまたは標準的な解決策を回避する正当な理由がある場合は、それらに注意する必要があります。誰かの手間を省くことができます。ただし、特定の技術は時間の経過とともに改善される可能性があるため、理由は当てはまらない場合があります。将来の開発者は、独自の判断を使用できます。

すべての短所を指摘することに多くの利点があるかどうかはわかりません。変更を行うことは実用的ではない場合があります。そうでない場合、他の優先順位が発生します。近いうちにそれらのいくつかを修正するかもしれません、そして、これは更新するためのもう一つのことになるでしょう。

私は個人的にそれを設計文書に入れません。設計文書には、その理由を説明する必要があります。

なぜデザインがそうであるかについての裏話が必要であると感じた場合、おそらくそれをwiki記事（またはあなたの会社が使用している知識ベース）に入れて、デザインの進化。人々はそれを読み、編集し、提案を追加できます。そうすれば、それは文書をbるのではなく、よりオープンな議論になります。

設計文書に根拠を入れることに同意します。

とにかく、

他の誰かが書いた設計文書を更新する過程で、私は謙虚なままで、そのような決定が下された理由を推測しようとはしません。

そう、

メンテナンス中に設計に加えられた変更についてのみ根拠を挿入します。