アジャイルの一部としてドキュメントを設計する

私の職場では、「アジャイル」とは「あいまいな要件、受け入れ条件の悪さ、幸運」を意味することが多いという課題に直面しています。私たちは、一般的な改善努力として、それに対処しようとしています。

そのため、その一環として、ユーザーストーリーレベルを超えて、システム内の特定の機能の影響の予備調査の結果を正確に反映し、私たちが持っている質問への回答を含む設計ドキュメントを生成することを提案していますビジネスに尋ねた。

これに効果的な基準はありますか？

現在、新しい機能が「泥の大玉」システムの複数の領域に影響を与える可能性がある状況に直面しており、この技術的負債により見積もりが上昇し始めています。うまくいけば、より思慮深い設計プロセスが役立つことがあります。

「あいまいな要件、悪い受け入れ基準、幸運を！」

うん、これはあなたがそれらを釘付けにしようとしてもあなたが得るのと同じ種類の要件です！（例として、政府のクライアントが作成するのに4年かかった10,000件の要件文書は、まだ矛盾、曖昧さ、内部的に矛盾した声明でいっぱいでした。漠然としたものは何でも手に入れることができると思いますか？）

そのため、このsh * tが発生することを理解し、それに対抗するのではなく、連携するアジャイルな方法が考案されました。

「何が欲しいですか」と尋ねることから始め、顧客は「このようなもの」と答えます。いくつかの作業を行った後、顧客に戻って「これはあなたが望んでいたものと同じですか？」と言い、顧客は通常「はい...」と言います。

最終的には、たとえ顧客がそれが何であるかを知らなくても、顧客が望むものを正確に入手できます！（地獄、彼らは彼らが望むものを決して正確に知らない）。

私たちのチームでは、アジャイルになって以来、実際に必要なドキュメントの量を絞り込んで理解しようとしています。これまでに学んだことを皆さんと共有できます。

何よりも先に、アジャイル/リーンドキュメンテーションに関するこの記事を必ずお読みください。非常に良い読み。

第二に、ストーリーの予備作業の後、設計文書の作成を再検討することを強くお勧めします。以前に試してみましたが、それは無駄であることが証明されています。前回のリリースの途中で、ストーリーのコードが配信された後にのみ設計ドキュメントを更新することにしました。そして今、それでも早すぎると思っています。

コーディングの前に設計ドキュメントを作成する理由を自問する必要があります。私たちにとって、これらが理由でした：

1. チームとして、ストーリーがデザインにどのように影響するかを理解する必要があります。
2. 新しい（または一時的な）メンバーがチームに参加するとき、または1年以上誰も取り組んでいないコードに戻るときに、設計ドキュメントがあると便利です。したがって、これらは組織の記憶に役立ち、コードがどのように機能するかを理解するのに役立ちます。
3. 設計ドキュメントは、リリース後にコードのトラブルシューティングを行う必要がある保守エンジニアにとって役立ちます。

（1）を満たすために、実際の設計文書を作成する必要はありません。あなたのチームはまだコーディングの前に設計段階を持っているべきですが、その段階はホワイトボードまたはナプキンの前で15分間のセッションと同じくらい簡単です。設計変更について議論するためだけに書くのに数日（数日ではないにしても）かかる実際の文書を作成する必要はありません。

（2）または（3）は、現在のストーリーの開発中には不要であり、その後の複数の反復で必要になることはほとんどありません。

また、チームメンバーが設計ドキュメントを作成/更新するたびに、コードが記述されないことにも注意してください。実際のコードの前にドキュメントを作成すると、コーディングを開始すると常に設計が変更されるため、ドキュメントの更新が必要になる可能性はほぼ100％です。そして、私たちのチームが学んだように、コードの後に​​デザインドキュメントを書いたとしても、その後のストーリーからのリファクタリングはデザインを変更します。

だから私がお勧めすること：

1. チームがコーディングの前にインテリジェントな会話を行えるように、最初は一時的な設計/モデルを十分に作成します。これらを保持することを期待してはならず、それらを形式化するのに時間を浪費しないでください。
2. 誰かがそれを必要とする場合にのみ公式の設計ドキュメントを作成します（つまり、チームは組織の記憶を本当に必要とします）
3. 安定化されたコードについてのみ設計ドキュメントを作成します。繰り返しごとに変更され続けるモジュールを文書化しようとしても意味がありません。
4. モジュール（または製品の一部）を完全に説明する設計ドキュメントを作成します。以前は、行う必要のある変更を文書化した設計ドキュメントを作成していました。これらのドキュメントは、リリースが完了するとすぐにまったく価値がなくなりました。
5. ドキュメントを非常に高レベルに保ちます。アーキテクチャと非常に高度なデザインをカバーする20ページを書くと、そのドキュメントはa）他の人に実際に読まれ、b）コードの一般的なレイアウトに慣れるのに役立ちます。詳細については、コードに直接アクセスできます。700ページの詳細な仕様を記述した場合、それらはほとんど常に現実とは一致しません。だれでも読むには多すぎるため、将来の変更が行われるたびに20ページではなく700ページを維持および更新しなければなりません。

アジャイルの「マントラ」は、完全にドキュメントなしでやることではありません。

アジャイルのマントラは、「包括的なドキュメントよりも動作するソフトウェア」を好むことです。ただし、マニフェストの下部にあるビットに注意してください。

つまり、右側のアイテムに価値がある一方で、左側のアイテムをより重視しています。」

ボブおじさんには文書化のポリシーがあります

必要性が即時かつ重要でない限り、ドキュメントを作成しません。

ドキュメントを作成しない言い訳としてアジャイルを使用する人もいますが、それは悪いアジャイルです。上記の引用で強調した部分を無視しています。

つまり、「現在、新しい機能が「泥の大玉」システムの複数の領域に影響を与える可能性がある状況に直面している」と言うとき、アジャイルになるには、これについて何かをする必要があります。

ドキュメントを入手したら、それを使用してコードをモジュール化します。この方法では、ドキュメントの長期的な必要性を削除することにより、ドキュメントを維持するための長期的な必要性（これは発生しません）を削除します。

すなわち。必要性を迅速かつ重要にします。

アジャイルに関することは、ドキュメンテーションの努力は本当にスクラムチームによって動かされる必要があるということです。開発者が外部のドキュメントでニーズを十分に満たしていないと感じた場合、ユーザーの話は彼らがやるまでブロックされます。開発者が適切なドキュメントを作成していないとビジネスが感じる場合、製品所有者はそれを受け入れ基準の一部にすることを主張します。このため、スクラムに移行して以来、ドキュメントがより集中的かつ効果的であることが実際にわかりました。

VersionOneを使用しますしてユーザーストーリーを追跡していますが、この方法は他のシステムにも適用されると確信しています。ファイルをユーザーストーリーに添付できます。設計文書を置くのに非常に便利な場所であることがわかりました。

私たちにとって非常にうまく機能した1つの例として、プロトタイプの構築後、可能な限り迅速に新しい回路基板の設計をテストする必要がありました。テストを必要とするすべてについて、2つのユーザーストーリーを作成しました。1つはテストの設計用、もう1つはテストの実行用です。設計ストーリーの受け入れ基準の1つは、テスト手順が実行ストーリーに完全に文書化されていることです。

テストの部分にたどり着いたとき、私が今まで見たよりもスムーズに進みました。ユーザーストーリーを開き、ステップバイステップの手順を実行しました。ドキュメンテーションは、ストーリーを完成させるために必要なものであり、それ以上でもそれ以下でもありませんでした。

バックログには、使用するチップのドキュメントを改善するためだけに別のストーリーがあります。これは、他のチームが自分の製品で簡単に入手できるようにするためです。

要約すると、ドキュメントに問題があると感じた場合、そのソリューションは、そのための個別のユーザーストーリーを作成したり、受け入れ基準の一部にしたりするのと同じくらい簡単です。

貧弱な要件について話すとき、私にとって最初に思い浮かぶのは、テスト基準を持っていることを確認することです。可能であれば、システムの既存の部分に対して再利用可能な自動テストケースを作成します。誰もがそれに慣れたら、コードを書く前にテストケースの作成に移ります。優れたテストケースは、システムの動作を文書化するために多くのことができます。

使用する特定の設計ドキュメントについては、他の人が既に述べたように、チームのニーズと彼らが引き受ける次のタスクに大きく依存しています。可能な場合は、使用するドキュメントを（コードから）生成できるツールを使用するか、ドキュメントからコードを生成してみてください。ドキュメントのメンテナンスは非常に高価になる可能性があるため、設計ドキュメントを永続化する場合は賢明に選択してください。

個人的には、コードとフィットネステストケースから生成されたクラス図で大成功を収めました。チームはクラス図をいくつか印刷し、製品所有者とマークアップセッションを行い、そこから見積もりを策定します。フィットネスに関する限り、スプレッドシートで必要なものを表現するのに非常に優れている数人の製品所有者と仕事をすることができて、それがフィットネス用のテーブルに変換されます。