製品設計の決定の背後にある理論的根拠を記録する効果的な方法は何ですか？

当社では、製品設計文書を使用していません。合計3人の従業員がいるため、製品設計に関するすべての議論は直接、またはSlackで行われます。（最新のメッセージの表示のみを許可する基本的なSlackパッケージも使用しています。）

当社の製品はまだ初期段階にあり、数か月前に決定された設計要素を頻繁に再検討しています。

私たちが悲惨なほど頻繁に直面する問題は、製品設計の決定が下された理由を忘れることです。これにより、同じ地面をリトレッドするのに何時間も無駄になります。

設計決定の背後にある理論的根拠をどのように効果的に記録できますか？

ワークフローはPivotal Trackerに基づいています。私に起こる解決策の1つは、関連するすべての設計決定の理論的根拠をユーザーストーリー自体へのコメントとして記録することですが、これは信頼できないようです。

100％明確にするために：私はコードの設計について話しているのではありません。私は、コードによって実現される製品の設計について話している。言い換えれば、「多重継承ではなく構成を使用してこのクラスを構成すべきか？」などの決定について話しているのではありません。「ログインする前に、ユーザーにメールアドレスを確認してもらう必要がありますか？」などの決定について話している。

ドキュメントの目的は、ビジネスが意思決定が行われた理由の記録を表示できるようにし、同じトピックに関するさらなる意思決定を支援することです。

設計決定の背後にある理論的根拠を書き留めて記録します。決定の対象となるアイテムの近くにあることが理想です（「ユーザーストーリー」ではありません。ユーザーストーリーは、実装方法を説明するものであり、実装方法を説明するものではありません）。

それが特にコメントの対象です- 理由を記録するために。特定のコードまたは構造の一部がそのように見えるです（そして、コードコメントだけを話しているわけではありません）。設計の主題が機能である場合は、その機能への紹介コメントを作成します。クラスの場合は、クラスの冒頭で理論的根拠についてコメントします。すべてが同じ構造に従う必要のあるクラスが多数ある場合は、それらのクラスを含むパッケージに別の設計文書（「readme」ファイルなど）を追加します。設計の主題がUML図である場合、図の説明セクションにコメントを追加します。

IMHOの設計文書には価値があるかもしれませんが、説明する項目から「遠く」にあるものを記述すると、すぐに矛盾する傾向があります。したがって、設計文書はできるだけ設計されたアイテムの近くに置くことをお勧めします。

コードのさまざまな場所に横断的に影響する設計上の決定を文書化する場合にのみ、個別の文書を使用します。それらを使用するときは、それらをコードベースの一部にし、設計されたサブジェクトの対応する階層レベルに配置してみてください（したがって、多くのソースコードファイルで構成される1つのモジュールの設計決定を行う場合、設計記述を配置します "そのモジュールの内部ではなく、1つのクラスファイルではなく、他のモジュールに有効な「トップレベルの説明」ではなく、SCCSの外部の個別のWikiでもありません。「高レベル」の製品を記録する場合幅広い設計上の決定、次に最上位のドキュメントが最良の場所かもしれませんが、このドキュメントが抽象化のレベルにとどまるようにしてください。

アジャイルなアプローチを検討してください。つまり、時間のリソースと優れたライティングスキルがあり、設計決定を合理的根拠とともに書き留めるのであれば、すべてを文書化するだけです。現実的に言えば、私はあなたがそのような位置にいないと仮定しています。 アジャイルなアプローチは、理論的根拠の文書化の重要な課題に役立つ可能性があります。多くの場合、論理的根拠が重要なものであるかどうかは後までわかりません。

全体的な観点から問題にアプローチしましょう。あなたたちはあなたの決定の論理的根拠を持っています。チームの頭脳である彼らは今、スクイーズウェアに閉じ込められています。大量のクレジット文書が取得されますが、sqishywareに理論的根拠を保存することはそれほど悪くはありません。私たちは実際に、重要なことを覚えている種として本当に良い。すべての大企業が「部族の知識」を持っているのは、それらの企業がその部族の知識をすべて文書化しようとする場合でもです。

これで問題が発生しました。あなたは、sqiushywareが十分に理論的根拠を保持していないことに気付いています。問題があることを認識し、それを解決する必要があることを特定することはあなたにとって良いことです！それは必ずしも簡単なステップではありません！そのため、解決策は、その根拠の一部をドキュメントにオフロードすることです。ただし、それだけでは十分ではありません。パズルの後半は決して忘れることができません。これは、判断を下す必要があるときに、論理的根拠をスクイウェアに再ロードすることです。クレイジーなものをすべて文書化する多くのチームを見てきましたが、コンテンツは実際には良い意思決定を支援するために編成されていないため、書き留められていても理論的根拠を忘れてしまいます。

したがって、2段階のプロセスがあります。スクイーズウェアの根拠を文書化する必要があります。次に、必要なときに合理性をスクイウェアに戻すために、ドキュメントが十分に整理されていることを確認する必要があります！課題がどこにあるのかを理解するのに十分な問題文があると思います。文書化するとき、通常、誰が後でそれを見るのか、または何を探しているのかがわかりません。同様に、ドキュメントを振り返ると、通常、何を探しているのかわかりません（せいぜいいつ知っているかもしれません）。

そのため、大企業はこれを2つの大きなブロックで処理しようとする場合があります。まず、ドキュメントを調査するときに必要なものに基づいて要件を作成します。次に、これらの要件を使用して、前述のドキュメントを開発するプロセスを構築します。そして、私があえて言うなら、誰も文句を言うでしょう。なぜなら、初日にはどのようなドキュメントがどのように見えるべきかを正確に知っている人はほとんどいないからです。ドキュメントは常に不完全であり、開発者は常にプロセスが重すぎると不平を言っています。

アジャイルになる時間です。

私のアドバイスは、あなたの文書作成プロセスを改善するための機敏な努力を始めることです。スクイウェアから文書化まで、スクイウェアに戻る9ヤード全体。プロセスが完全ではないために情報が失われることを前もって認識してください。ただし、プロセスを把握しようとしているので大丈夫です。すべてのソリューションに適合する1つのサイズを作成しようとすると、もっと見逃してしまいます。

私が見たいいくつかの特定の情報：* 非公式のドキュメントを調べてください。 正式なドキュメントは素晴らしいものですが、時間がかかります。文書化の目的の1つは、開発者のスクイーズウェアから情報をリリースし、それを紙に載せることです。非公式の文書化により、そのためのコストは最小限に抑えられます。

• 信頼できないドキュメント形式を受け入れます。 最初は何も正しくありません。データを取得し、後で信頼性を高める方法を見つけた方がよいでしょう。たとえば、理論的根拠を<rationale> </ rationale>ブロックまたは類似のブロックに記録すると、そのデータを後で簡単に収集できます。現時点では、ユーザーストーリーに理論的根拠を保存するだけで十分です。
• 組織の価値を決して忘れないでください。 チームとして、ドキュメンテーションの理論的根拠をどのように検索するのが好きかを見つけて、それをドキュメント化してみてください。各チームには異なるプロセスがあります。私のチームの1つで、理論的根拠のあるチケットをすぐに見つけることができませんでした。私たちができることは、重要なコード行svn blameを見つけ、それがいつ変更されたのか、そしてなぜそれを見つけてチケットを調べに行くことです。そこに着いたら、通常、必要な根拠をすべてチケットに記入します。それはちょうど私たちのために働いた、あなたのために働くものを見つけます。
• オーガニックなドキュメントは時間とともに成長する可能性があります。 開発者が、それを書くのに必要な日にどの理論的根拠が最も重要であるかを知ることはまれです。通常、後で重要なものを見つけます。開発者が自分の合理的根拠の小さな庭を管理できるようにするドキュメントのグルーミングプロセスがある場合、重要なものが浮上します。さらに重要なのは、理論的根拠が変わる可能性があることです。2つの異なる理論的根拠を持つ2つの異なる変更が、両方に有効な単一の理論的根拠によって実際に最もよく説明されていることに気付くでしょう。これで、あなたと意思決定の間のコンテンツが少なくなります！

MediaWikiまたは同様のWikiソフトウェアのプライベートインスタンスをセットアップすることをお勧めします。そこでのコンテンツの整理と再整理は非常に簡単で、新しいディスカッションをコピーして、関連するWiki記事のディスカッションタブに直接貼り付けることができます。前回の仕事で、すべてのアーキテクチャとAPIドキュメントにMediaWikiを使用しましたが、これは命の恩人でした。

12か月後に変更するように求められるコーダーの観点から考えてください。

このビジネスルールを自動テストとして追加すると、変更が行われ、失敗したテストから矛盾する要件が得られます（そして、元の要件に関連付けられた人とそれを指定する理由を取得することが望ましい）。

デザインドキュメント（BPMNダイアグラム、トランザクションダイアグラム、ホワイトボードの写真などを配置する場所）は、コードと同様で、実行不可能なフォームであると考えています。レコードはコードコメントに似ていますが、設計で事前に指定された（テスト可能な）要件です。おそらく、あなたがまだコードを設計しているアジャイルショップなら、あなたはそれを書く前の最後の最後にそれをするだけです。これを、他のすべてのプロジェクトドキュメントと共にコードベースに保持します。

何をするにしても、検索可能な方法で保存されていることを確認してください（たとえば、新しい変更を指定するときに「認証」に関連するすべてのビジネスルールをプルアップすることができます）。

いつものように、何かを書くときは、対象読者が誰であるかを自問する必要があります。私は、現在または将来の同業者の開発者向けに設計文書があると強く信じています。このドキュメントは、彼らが私が何を構築しているのか、何を構築したのか（高レベルの概要）、さらに重要な理由を理解するのに役立ちます。これは、あなたが検討した代替案、それぞれの長所と短所を文書化する場所です。

一部のデザインが人々の頭の中に住んでいても大丈夫だと言うと、開発者が別の仕事を見つけて、彼らと一緒にその貴重な情報を取得することはできません。

コードを唯一の設計ドキュメントにすることは、虫眼鏡を使って街を探索するようなものです。マップは非常に便利です（残念ながら、ソースコードに相当するGPSはありません）。

設計文書はコードよりもさらに速く腐ることに同意します。そして、2つの間に検証は不可能であるため、あなたができる唯一のことはそれらを密接に保つことです。日付の付いた設計文書であるIMOは、依然として貴重な情報を提供します。