私は CMMI レベル 5 認定の会社で働いていますが、私が嫌いなことの 1 つは、準備するドキュメントの量です (プログラマーとして、私はすでにドキュメントが嫌いです)。PID (プロジェクト開始ドキュメント)、ビジネス要件、システム要件、技術仕様、コード レビュー チェックリスト、イシュー ログ、欠陥ログ、構成管理計画、構成管理チェック リスト、リリース ドキュメントなど、たくさんのドキュメントがあります。 ...
これらのドキュメントのほぼ 90% は、QA 監査のために作成されたものです :) .. プロジェクトにとって最も重要なドキュメントは何だと思いますか? 他の開発者が長期的に使用できるドキュメントは何ですか?
ここであなたの良い習慣を共有してください。自分のプロジェクトや、長期的に立ち上げようとしている会社で使用したいと考えています。
ありがとう
ユーザーストーリー、バーンダウンチャート、コード
プロジェクトの観点から見ると、最も重要な文書は、プロジェクト計画、構成管理計画、品質計画など、通常計画という言葉を含む文書です。
あなたが説明していることは、プロセスの改善において一般的であり、通常は 2 つの主要な原因に対応します。1 つは、システムが実際にやり過ぎて、実際の作業を妨げていることです。もう 1 つは、あなたの質問で実際に回答されています。ドキュメントが監査のためだけに作成されているわけではありません。ドキュメントが他の開発者にとってどれほど役立つかだけでなく、プロジェクトや会社全体に焦点を当てる必要があります。
通常、人は自分自身の視点から物事を見ますが、時には全体像を見る必要があります。
私は古い 4+1 ビューのファンです。
ユース ケース ビュー (別名ユーザー ストーリー)。適切なユース ケース、明確に定義されていない前向きなユース ケース、分解が必要な叙事詩など、いくつかの形式があります。
論理ビュー。「静的」ビュー。UML クラス図などは、設計ドキュメントとしてここでうまく機能します。これには、さまざまなプロトコルの要求および応答形式も含まれます。ここで、RESTful な要求と応答を文書化します。これには、REST URI 設計が含まれます。
プロセス ビュー。「動的」ビュー。UML アクティビティ図、シーケンス図、ステートチャートなどは、設計ドキュメント用です。場合によっては、単純な物語がうまく機能します。その他のケースでは、Stateデザイン パターンがあり、ステートフル オブジェクトがどのように相互作用するかを示すために、クラス図とステートチャートの組み合わせが必要です。
これには、プロトコル (REST など) も含まれます。ここで、さまざまな REST 要求の特別な処理を定義します。
これには、認証または承認ルール、およびセキュリティ、ロギングなどのその他の分野横断的な側面も含まれます。
コンポーネント ビュー。展開のために構築している部分。これには、依存するもの、モジュールとパッケージの構造などが含まれます。これは多くの場合、単純なコンポーネント図またはコンポーネントとその依存関係のリストです。
展開ビュー。デプロイされたコードからこれを生成しようとします。Python を使用しているため、epydoc を使用して API ドキュメントを作成します。また、Sphinx を使用して、モジュール ドキュメントをソフトウェアのこのビューにインポートします。
これには、パラメーター、設定、および構成の詳細も含まれます。
ただし、これでは十分ではありません。
プロジェクトが開始されると、一連のスプリントを通じてこれに取り組む必要があります。
最初のスプリントでは、ユース ケース ビューのみが構築されます。
その後のスプリントでは、ユース ケースを実装するための「アーキテクチャ」を構築します。アーキテクチャ ドキュメントには 4+1 ビューがありますが、高度な抽象化が行われています。モデル スキーマの構造、要求と応答、RESTful 処理、その他の処理、予想されるコンポーネントなどを要約します。展開ビューはありません。通常、オペレーター ガイドと API ドキュメントは、アーキテクチャの展開ビューとして参照されます。
次に、設計と建設のスプリントで、さまざまなコンポーネントの詳細な 4+1 ビュー ドキュメントを作成 (および更新) します。
次に、スプリントをリリースして、デプロイ ビューを構築 (および更新) します。