ドキュメント駆動開発について何を知っていますか?

開発プロセスでドキュメントが必要なのはなぜでしょうか?

コード自体が文書化されているというこの記述についてはどうでしょうか?

最も一般的なシナリオを考えてみましょう。システムのコード (プログラム、プロジェクト、または製品) は長期間にわたって作成されており、このプロセス中にチームが徐々に変更され、開発者が退職するとシステムに関する特定の知識がチームに持ち去られます。

このような場合、どうすればいいでしょうか?

最も簡単な答えは、システムが元の要件を満たしていることを確認するために、実装の詳細をすべて取り込んだ仕様を作成することです。

しかし、このようなドキュメントを事前に作成するのは非常に難しく、開発プロセス中に実装の詳細が変更される可能性があります（市場への適応/メカニックに対する新しい要求など）。では、 バス係数を改善するために何を考案できるでしょうか？

上記の問題に対処するための可能な解決策の 1 つとなるフローをたどってみます。

要件とRFC

まず、利害関係者の要件に基づいて初期設計を説明し、それを文書化する必要があります。その後、このドキュメントを他のチームと共有し、フィードバックを要求できます。たとえば、特定の機能の実装を依頼したり、初期設計についてコメントしたり、特定のインターフェースを修正したりします。このようなドキュメントはRFC と呼ばれます。

RFC （Request for Comments）は、開発者、設計者、その他のチームを含む関係者間で配布され、フィードバック、コメント、提案を収集する文書です。仕様ほど詳細ではなく、初期の問題、タスク、およびソリューション ドメインのみが含まれます。より柔軟性が高いため、設計の変更を積極的に受け入れることができ、タスクを深く理解し、質の高い思慮深い意思決定を促進します。

設計コミットメントとADR

さて、技術要件を定義し、他のチームからの要件を収集しました。次は何でしょうか?

この段階では、システム設計とそれが実行するすべての主要機能を最終決定する必要があります。この目的のために、 ADR を作成します。

ADR (アーキテクチャ決定記録) は、ソフトウェア開発プロセス中に行われた重要なアーキテクチャ上の決定を記録する文書です。各ADRには、特定の高レベルのアーキテクチャ上の決定、そのコンテキスト、検討された代替案、下された決定、および他の詳細よりもこれらの特定の詳細を選択した理由が記述されています。

このようなドキュメントにより、すべてのチーム メンバー (および他のチーム) が設計の基盤となる原則と価値を理解できるようになります。数年後に新しい開発者がチームに参加し、「なぜこのようにしたのですか?」と尋ねられた場合、このドキュメントを提示することで、すべての質問に答えることができます。

仕様

次は、コードとその仕様を記述する段階です。この段階では、各機能を徹底的に検討し、同時にすべての情報と実装の詳細を特別なドキュメントにまとめます。このドキュメントには、システムの現在の低レベルの要件が反映されている必要があります。

重要なポイント：ソフトウェアのライフサイクル中に、このような仕様は大幅に変更される可能性がありますが、それは問題ありません。ただし、コードベースが管理不能にならないように、元の設計とアーキテクチャを維持することが非常に重要です。

テスト計画

なぜ必要なのでしょうか。テスト プランは、仕様に従って記述されたコード (コードを作成し、このコードが合格するようにテストします) に基づいて構築するのではなく、正しく処理する必要がある重要なシナリオを含む設計に基づいて構築することが重要です。また、このようなテスト プランを他のチームにレビュー用に提出して (統合用または追加のテスト用)、さまざまな状況でシステムがどのように動作するかを明確にすることも非常に便利です。

何が含まれていますか?

• あらゆるシステム運用シナリオ

  • ハッピーパス
  • 悲しい道
  • エラー処理

• システム運用中に維持する必要があるすべての不変条件

• 開始時にシステムの状態を確認するための受け入れテスト（ネットワーク上のデータなどの環境を考慮する必要があります）

  
  

設計を確定し、コードと仕様を書き、テスト計画をまとめました。すでにかなりしっかりした感じですが、他に何を追加できるでしょうか?

展開計画

このような計画は、バス係数を改善し、チームメンバーがシステムを展開してその状態を確認できる条件を作成するために、ある程度必要になる可能性があります。

なぜそれがないのでしょうか? なくてもできますが、現実の世界では、システムのさまざまな部分に多くの人が責任を負っている大規模なチームがあり、デプロイメント プロセスは DevOps に完全に委任されている可能性があります。テストを記述し、CI に配置し、脆弱性をチェックしているので、他に何か必要なのでしょうか? おそらくそうではないかもしれませんが、多くの場合、テストはシステムの現在の状態を考慮せず、私たちが望むものとはまったく異なるテストになります。

展開計画には次の内容が含まれます。

• 展開を実行するために実行する必要があるアクションの完全な説明
• 展開パラメータ:
  • 環境変数
  • 初期状態
  • 打ち上げパラメータ
• どの段階でも何か問題が発生した場合の計画
• 可能であればバックアッププラン
• 展開の継続が不可能な場合にシステムを到達させる必要のある状態
• 展開後に実行する必要があるアクション
  • 他のチームに通知する
  • 必要に応じて必要な統合を有効にする

何も複雑なことではないですよね? 特定の更新に関するこのようなドキュメントがあれば、バス係数が大幅に向上し、特定の個人への依存を防ぐことができます。それが私たちが望んでいることではないでしょうか?

結論

ソフトウェア開発プロセスでは、コードを書くだけでなく、開発の全段階を通じて理解と一貫性を確保するドキュメントを作成することも重要です。ドキュメントはコード自体である場合もありますが、経験上、特に開発中にチームが変更された場合や、プロジェクトが進化して新しい要件に適応する場合、システムの品質、安定性、将来の拡張性を維持するためにドキュメントが非常に重要であることがわかっています。

ドキュメントには、 RFC (Request for Comments)、 ADR (Architecture Records)、仕様、テスト計画、展開計画などが含まれます。これにより、チーム内での知識の保持が保証され、新しい従業員をプロジェクトに統合するプロセスが簡素化され、システム全体の信頼性と変更に対する耐性が向上します。