製品設計の決定の背後にある根拠を記録する効果的な方法は何ですか？
当社では製品設計書は一切使用しておりません。私たちには合計3人の従業員がいるため、すべての製品設計の議論は直接、またはSlackで行われます。 （また、最新のメッセージのみを表示できる基本的なSlackパッケージを使用しています。）
当社の製品はまだ初期段階にあり、数か月前に決定された設計要素をよく見直します。
悲惨なほど頻繁に直面する問題は、製品設計の決定がなされた理由を忘れることです。これにより、同じ場所を再利用して無駄に時間を無駄にすることになります。
設計決定の根拠を効果的に記録するにはどうすればよいですか？
私たちのワークフローはPivotal Trackerに基づいています。私に発生する1つの解決策は、関連するすべての設計決定の根拠をユーザーストーリー自体のコメントとして記録することですが、これは信頼性が低いようです。
100％明確にするために：私はコードの設計について話しているのではありません。私はコードによって実現される製品のデザインについて話しています。つまり、「多重継承ではなく合成を使用してこのクラスを構造化する必要があるか」などの決定について話しているのではありません。 「ログインする前にユーザーにメールアドレスの確認を要求する必要があるか」などの決定について話している。
文書化の目的は、ビジネスが決定が行われた理由の記録を表示して、同じトピックに関するさらなる決定を行うのを支援できるようにすることです。
設計決定の背後にある根拠を書き留めて記録します。理想的には、決定の対象となるアイテムの近く（「ユーザーストーリー」ではありません。ユーザーストーリーは、どのようにではなく、どのように実装する必要があるかを説明するものです）。
これが特にcommentsが-を記録するために作成されるものですwhy特定のコードまたは構造がそのように見えます（そして私はコードコメントだけで話しているわけではありません）。デザインの対象が関数である場合は、関数に導入コメントを付けます。クラスの場合は、クラスの冒頭にその理由をコメントしてください。すべてが同じ構造に従う必要のある一連のクラスがある場合は、それらのクラスを含むパッケージに個別の設計ドキュメント（「readme」ファイルなど）を追加します。設計の主題がUML図である場合は、図の説明セクションにコメントを追加します。
IMHO設計ドキュメントには価値があるかもしれませんが、それらが説明するアイテムから「遠く離れている」ものについて説明している場合、それらはすぐに一貫性が失われる傾向があります。したがって、私の推奨事項は、設計ドキュメントを可能な限り設計されたアイテムの近くに置くことです。
横断的な方法でコードのさまざまな場所に影響する設計上の決定を文書化する場合にのみ、個別の文書を使用してください。それらを使用するときは、それらをコードベースの一部にして、設計されたサブジェクトの対応する階層レベルに配置するようにしてください（多くのソースコードファイルで構成される1つのモジュールの設計を決定する場合は、設計の説明を配置します "そのモジュール内にありますが、1つのクラスファイル内ではなく、他のモジュールに有効な「トップレベルの説明」上ではなく、SCCSの外部にある別のWiki内でもありません。「高レベル」の記録が必要な場合、製品幅広いデザイン決定、そしてトップレベルのドキュメントがおそらく最良の場所かもしれませんが、このドキュメントがその抽象化のレベルに留まるようにしてください。
アジャイルアプローチを検討してください。つまり、時間のリソースと優れたライティングスキルがあり、設計上のすべての決定事項をその根拠とともに書き留める場合は、すべてを文書化します。現実的には、あなたがそのような立場にないことを前提としています。 アジャイルアプローチは、理論的根拠を文書化するための重要な課題に役立ちます。多くの場合、どの論理的根拠が重要なものであるかを後で知ることができません。
全体論的な観点から問題に取り組みましょう。君たちはあなたの決断に根拠を持っている。彼らは今、スクイーズウェア、つまりチームの頭脳に閉じ込められています。クレジットドキュメントの量は増えますが、理論的根拠をsqishywareに保存することはそれほど悪いことではありません。私たちは実際に重要なことを覚えている種として本当に種として優れています。その理由は、それらの企業がすべての部族の知識を文書化しようとするときでさえ、すべての大企業が「部族の知識」を持っている理由です。
今、あなたは問題を抱えています。 sqiushywareが十分な根拠を保持していないことがわかります。問題があることを認識し、それを解決する必要があることを識別するために役立ちます！それは必ずしも簡単なステップではありません！したがって、その根拠の一部をドキュメントにオフロードすることが解決策であると確信しています。しかし、それだけでは不十分です。私たちはパズルの後半を決して忘れることができません。それはあなたが決定を下す必要があるときに論理的根拠をスクイーズウェアに再ロードすることです。私はクレイジーなものすべてを文書化する多くのチームを見てきましたが、内容は実際には適切な決定を下すのに役立つように編成されていないため、書き留められていても、根拠を忘れてしまいます。
したがって、2つのステップのプロセスがあります。理論的根拠をスクイーズウェアから文書化する必要があります。次に、必要なときに合理的なものをスクイーズウェアに戻すために、ドキュメントが十分に整理されていることを確認する必要があります。今、私たちは、課題がどこで好まれるのかを理解するのに十分な問題文があると思います。ドキュメント化しているとき、通常、後で誰がそれを見るのか、または何を探しているのかわかりません。同様に、ドキュメントを振り返っているときは、通常、何を探しているのかわかりません（せいぜいいつ知っているかもしれません）。
したがって、大企業はこれを2つの大きなブロックで処理しようとする場合があります。最初に、ドキュメントを調査するときに必要なものに基づいて要件を作成します。次に、それらの要件を使用して、前述のドキュメントを開発するプロセスを構築します。そして、もし私がそう言うとすれば、誰もが不満を言うでしょう。なぜなら、ほとんど誰も正確に初日にドキュメントがどのように見えるべきかを知らないからです。ドキュメンテーションは常に不完全であり、開発者は常にプロセスが面倒であると不平を言っています。
アジャイルに移行する時間。
私のアドバイスは、文書化プロセスを改善するための俊敏な取り組みを開始することです：スクイーズウェアから文書化し、スクイーズウェアに戻るまでの9ヤード全体。プロセスが完全ではないために一部の情報が失われることを前もって認識しますが、それでもプロセスを理解しようとしているので問題ありません。すべてのソリューションに適合する1つのサイズを作成しようとすると、さらに失敗します。
私が見てみたいいくつかの特定のヒント：* 非公式ドキュメントを探す正式なドキュメントはすばらしいですが、時間がかかります。文書化の目的の1つは、開発者のスクイーズウェアから情報をリリースして紙に載せることです。非公式のドキュメントは、そうするためのコストを最小限に抑えます。
- 信頼できないドキュメント形式を受け入れます。最初は何も正しくありません。データを取得して、後で信頼性を高める方法を理解することをお勧めします。たとえば、理論的根拠を<rationale> </ rationale>ブロックまたは類似のもので文書化すると、後でそのデータを簡単に収集できます。今のところ、ユーザーストーリーに理論的根拠を格納することは問題ありません。
- 組織の価値を決して忘れないでください。チームで、ドキュメント内の理論的根拠をどのように検索したいかを調べ、それを文書化しようとします。各チームには異なるプロセスがあります。私のチームの1つでは、根拠のあるチケットをすぐに見つけることができませんでした。重要なコード行を見つけて、
svn blame変更の時期と理由を確認するには、チケットを確認してください。いったんそこに着くと、通常、必要なすべての理論的根拠をチケットに直接置きました。これでうまくいきました。何がうまくいくかを調べてください。 - 有機ドキュメントは時間とともに成長する可能性があります。開発者がそれを書くのに必要な日に最も重要な理論的根拠を知ることはまれです。通常、どれが重要かは後で確認します。開発者が独自の合理的な庭を管理できるようにするドキュメントのグルーミングプロセスがある場合、重要なものが表面化します。さらに重要なのは、理論的根拠が変わる可能性があることです。 2つの異なる理論的根拠を持つ2つの異なる変更は、両方に対して機能する単一の理論的根拠によって最も適切に説明されていることに気付くでしょう。今、あなたと決定の間のコンテンツが少なくなっています！
12か月後に変更するよう求められるコーダーの観点から考えてみてください。
このビジネスルールを自動テストとして追加すると、変更が行われ、失敗したテストから矛盾する要件が取得されます（うまくいけば、元の要件に関連付けられている人物と、それを指定した理由を把握できます）。
私はデザインドキュメント（BPMNダイアグラム、トランザクションダイアグラム、ホワイトボードの写真などを配置する場所）をコードに似ていると考えています。これは単に実行不可能な形式です...つまり、レコードはコードコメントに似ていますが、（テスト可能な）要件は設計で事前に指定されています。おそらくあなたがまだアジャイルショップでコードを設計しているなら、あなたはそれを書く前の最後にそれを行うだけです。これを他のすべてのプロジェクトドキュメントと一緒にコードベースに保存します。
何をするにしても、それが検索可能な方法で保存されていることを確認してください（たとえば、新しい変更を指定するときに、「認証」に関連するすべてのビジネスルールをプルアップしたい場合があります）。
MediaWikiまたは同様のWikiソフトウェアのプライベートインスタンスをセットアップすることをお勧めします。そこでのコンテンツの整理と再編成は非常に簡単で、新しいディスカッションをコピーして、関連するWiki記事のディスカッションタブに直接貼り付けることができます。私はすべてのアーキテクチャとAPIドキュメントの最後の仕事でMediaWikiを使用しましたが、それは命の恩人でした。
いつも何かを書くときは、意図する対象者が誰であるかを自問する必要があります。私は、現在または将来の開発者のために、設計ドキュメントが存在すると強く信じています。このドキュメントは、私が何を構築しているか、何を構築したか（高レベルの概要）、さらに重要な理由を理解するのに役立ちます。検討した代替案、それぞれの長所と短所を文書化する場所です。
一部のデザインが人々の頭の中で生きても大丈夫だと言うと、開発者が進んでさまざまな仕事を見つけ、それらの貴重な情報を彼らに提供することを除外します。
あなたのコードを唯一の設計ドキュメントにすることは、虫眼鏡を使って街中を探索するようなものです。地図は非常に便利です（残念ながら、ソースコードに相当するGPSはありません）。
設計ドキュメントは、コードよりも速く腐敗することに同意します。また、2つの間で検証を行うことはできないため、できることは、両者を近づけることだけです。日付の付いた設計ドキュメントであるIMOは、依然として貴重な情報を提供しています。