開発アプローチ文書に何を含めるべきですか？[閉まっている]

私は、オフショアリソースが私たちのプロジェクトに移行するときに、オフショアリソースの「開発アプローチ」ドキュメントを共同制作している最中です。

私たちの会社が使用した最新の（類似した）ドキュメントは80ページを超えており、これにはコーディング標準/規約のドキュメントは含まれていません。

私の懸念は、このドキュメントが消費可能ではないために失敗することです。

開発アプローチ文書には何を含めるべきですか？このトピックに関して適切なガイドラインはありますか？

編集：開発アプローチ文書には、ソフトウェアの設計、構築、およびテスト中にソフトウェア開発者が使用するプラクティスとテクニックの詳細を記載する必要があります。

私が働いていた会社の1つでは、この全プロセス指向のアプローチで多くのドキュメントを処理しました（そのほとんどはプロジェクトマネージャーからの入力を求められていました）。しかし、長さと説明にもかかわらず、私はそれが人々をサポートするためにほとんど使用されていないことに気づきました-本当の開発者。

それで、私は「開発者を助ける」という特定の目的で自分を引き受けることにしました。私が始めた最も重要なことは、最も基本的な質問、つまり実際の FAQ を収集することです。

私が学んだことは、特定のプロセスを採用する場合、ほとんどの人にとって重要なことであり、事前のアイデアを持っていないかもしれないが、ロジックを理解すればすぐに感謝する多くのことです。

このようなドキュメントが役立つはずの主要なトピックは次のとおりです。

1. 開発から展開へのプロセス-コードをどのように編成、コンパイル、公開する必要がありますか（DLL、ライブラリ、実行可能ファイル、インストーラー、Webページの形式で、どのように展開およびテストしますか）？

2. どのようにバージョン管理を行うべきですか？（そして、初心者がいる場合はなぜか）。リポジトリの構造、行動規範-チェックインが受け入れられる場合と受け入れられない場合、バージョン/タグが発表されたとき、パッチ、マージがどのように適用されるか、パッチまたはリリースが完了したと宣言されています

3. 方法論の実行-俊敏性はありますか。事前に設計を行いますか、どの方法論を使用していますか？これを考えると、それは特定の会社の修正になる可能性があります。さて、ほとんどの人にとって、彼らは私たちがそれを与えられたプロジェクトにどのように実装するのかを知りたいのです。これは、人々がさまざまなマイルストーンと潜在的に重要なものを視覚化できるようにするプロジェクトに非常に特有です。研究指向のプロジェクトでは、「重要なアルゴリズムを上に構築する前に常に検証する」ことをシュリンクラップで示し、機能の正確さと重要性に焦点を当てます。

4. コミュニケーションの責任-正式なコミュニケーションをどのように行うかを定義する-これは、特定の人々が互いに話し合うことができるかどうかでは行われません-しかし、人々はどちらが発表するのに十分重要であるか（問題、設計決定、機能の凍結）についての感覚を持っている必要がありますまたは実装に進む前に議論されました。

5. 最後に、すべての人がコード品質、コーディング標準、および一般的に大丈夫か衛生レベル以下であると私たちが考えるものについて共通の理解を持っている必要があります。

すべてのプロジェクトをそのようなドキュメントから始めたいと思いますが、それは簡単ではありません。しかし、重要なことは、日々の行動と開発者の選択に関連するすべての問題に対処することです。これは、市場にリリースする複数のリリースを配信する必要がある場合に長くかかります。

最後に、可能な限り非公式にすることをお勧めします。通常、プロセス指向の人たちは、文脈の外で誤解される可能性のある非公式のドキュメントはあまり好きではありません。ただし、開発者をつなぐ方法で行う必要があります。

「開発アプローチドキュメント」と呼ばれるものは、通常、ソフトウェアプロジェクト管理計画と呼ばれます。（ソフトウェアプロジェクトプランまたはソフトウェア開発プランと呼ばれることも聞いたことがあります。）これらの条件があれば、そこにあるいくつかのサンプルについてGoogleにアクセスできるはずです。Victor HurdugaciとDonal Fellowsが述べたように、作成するソフトウェアプロジェクト管理計画は、（1）ニーズに合わせて調整され、（2）状況の変化に応じて最新のドキュメントとして更新されます。そうは言っても、これまで一度も書いたことがなく、他に何を入れればよいかわからない場合、ゼロから書くのは難しいかもしれません。

IEEE標準1058（ソフトウェアプロジェクト管理計画のためのIEEE標準、1998年）によるガイダンスがいくつかあります。ここに掲載されている標準のコピーがあります。この計画はかなり重いと思いますが、アイデアを得るにはまともな場所です。オフショアのチームのためにすべて書面で書く場合は、追加の重みが必要になる場合があります。また、かなり良い概要があり、ソフトウェアプロジェクトを計画する方法に関する優れた説明がいくつかあります。本の中で、私は従来の（アジャイルでない）ソフトウェアプロジェクトを頻繁に参照しています。Futrell、Shafer、ShaferによるQuality Software Project Managementです。

アプローチ文書は「ここにもそこにもない」文書です。これは、ソフトウェアアプリケーション開発組織のプロジェクトマネージャー（ソフトウェア開発マネージャー）からビジネス組織のプロジェクトマネージャー（ベンダーマネージャー）が一般に尋ねたドキュメントです。

このドキュメントの目的は、Business Org PMのニーズによって異なります。

ハードウェアアーキテクチャ、システム機能、通信計画、構成計画、リソース読み込み計画、テクノロジースタック、アプリケーションアーキテクチャなどを含めることができます。

繰り返しますが、上記のリストはニーズに基づいて可変です.. :)

そのような文書に関する正式な文献はまだ見ていません。標準的な著者によるものがある場合は、プレスマンなどが共有します。

または私は何かが欠けていますか？

私たちの会社が使用した最新の（類似した）ドキュメントは80ページを超えており、これにはコーディング標準/規約のドキュメントは含まれていません。

すでにいくつかのドキュメントがあるので、それが出発点です。自問してみてください：

1. このドキュメントで何が役に立ちますか？
2. 何が欠けている？
3. なぜ私はこのドキュメントを使用するのでしょうか（しません）？

答えが出たら、不要なものを切り取り、足りない部分を追加します。

ドキュメントの実際のコンテンツは、利用可能なリソースによって異なり、提供された情報を使用して推測するのは難しいと思います。

ヒント：このドキュメントは時間をかけて調整したいので、書きすぎないようにしてください;）

要件の変化や、使用する言語、ライブラリ、フレームワークのセットの変化に伴い、開発慣行は時間とともに変化します。この変更は避けられず、紙に書いたものはすぐに（ほとんど）古くなります。これに対処する方法は？すべてをwikiに保管し、社内外のチームの全員に、最新で関連性のあるものを維持できるようにすすめます。

死んだ文書から生きた文書に一歩踏み込んだら、何を入れるべきかという議論の緊急性は低くなります。今考えられることを入れて、後で戻ってくるだけです。（良い点は、最初にドキュメントを書くためにすべてを理解する必要がないことです。）また、古い80ページのドキュメントの古いコンテンツをすべてシードすることもできます。これにより、他に何もない場合でも多くの概要資料が得られ、退屈なものの巨大なSCADを書くことを考える必要がなくなります。

ドキュメントは短くしてください。新聞スタイルの構造化を使用します-高レベルの詳細から始めて、詳細を説明します。標準プラクティスを含める代わりに、それらを参照し、標準からの逸脱を詳しく説明します。

1：社内で既にプロジェクトを行っている場合は、そのプロセスに参加します。多分彼らにあなたのプロジェクト開発の管理を下請けにすることさえします。車輪を再発明しないでください。

2：まだ社内で開発を行っていない場合は、使用している請負業者がプロジェクトに使用する適切な方法論を持っていることを主張します。次に、その方法論を使用します。

信頼するが検証する。あなたは長期的にゴミを取り除こうとしています。だから彼らに何もさせないでください、最後に成果物だけを使ってあらゆるプロセスに従ってください。先に進む前に、成果物を完成させて確認するように要求します。

それを超えて、私は基本的に@Dipanで同上です