アジャイルの一部としてドキュメントを設計する
私の職場では、「アジャイル」が「あいまいな要件、受け入れ基準の悪さ、幸運」を意味することが多すぎるという課題に直面しています。私たちは、一般的な改善努力として、それに対処しようとしています。
したがって、その一環として、ユーザーストーリーレベルを超えて、システム内の特定の機能の影響に関する予備調査の結果を正確に反映し、私たちが持っている質問への回答を含む設計ドキュメントを生成することを提案しますビジネスに尋ねた。
これに有効な基準はありますか？
現在、新しい機能が "泥の大きなボール" システムの複数の領域に影響を与える可能性がある状況に直面しており、この技術的な負債により見積もりが上昇し始めています。うまくいけば、より思慮深い設計プロセスが役立ちます。
"あいまいな要件、悪い受け入れ基準、幸運！"
うん、これはあなたがそれらを釘付けにしようとしてもあなたが得るのと同じ種類の要件です！ （例として、政府のクライアントが作成するのに4年かかった10,000の要件ドキュメントは、依然として矛盾、曖昧さ、さらには内部的に矛盾するステートメントでいっぱいでした。4年の要件ドキュメントでは、適切で正確な要件が得られない場合、漠然としないものを手に入れることができると思ったことはありますか？）
だから...アジャイルな方法は、これが起こることを理解し、それに逆らうのではなく、それに取り組むために発明されました。
あなたは「何が欲しいのか」と尋ねることから始め、顧客は「このような何か」で応答します。いくつかの作業を行った後、顧客に戻って「これはあなたが欲しいものですか？」と言うと、顧客は通常「はい、しかし...」と言った後、「何が欲しいですか」と尋ねます。
最終的には、顧客がそれが何であるかを知らなくても、顧客が望むものを正確に得ることができます。 （地獄、彼らはnever彼らが何を望んでいるかを正確にではなく知っている）。
私たちのチームでは、アジャイルに移行して以来、実際にどれだけのドキュメントが必要かを絞り込んで理解しようと努めてきました。これまでに学んだことを皆さんと共有できます。
何よりもまず、これを必ず読んでください アジャイル/リーンドキュメントに関する記事 。とても良い読み物です。
第二に、ストーリーについての予備作業の後、設計ドキュメントの作成を再検討することを強くお勧めします。私たちは以前にそれを試しました、そしてそれは無駄であることが証明されました。前回のリリースの途中で、ストーリーのコードが配信された後でのみ、設計ドキュメントを更新することを決定しました。そして今でもそれは早すぎると思います。
コーディングする前に、なぜ設計ドキュメントを作成するのかを自問する必要があります。私たちにとってこれらは理由でした：
- チームとして、ストーリーがデザインにどのように影響するかを理解する必要があります。
- 新しい（または一時的な）メンバーがチームに参加するとき、または1年以上誰も作業していないコードに戻るときに、設計ドキュメントがあると便利です。したがって、組織の記憶にコードがどのように機能するかを理解するのに役立ちます。
- 設計ドキュメントは、リリース後にコードのトラブルシューティングを行う必要があるメンテナンスエンジニアに役立ちます。
（1）を満たすために、実際の設計ドキュメントを作成する必要はありません。チームにはコーディングの前に設計段階がまだあるはずですが、その段階はホワイトボードまたはナプキンの前で15分のセッションと同じくらい簡単です。設計変更について話し合うためだけに書くのに数日（数日ではないにしても）かかる実際のドキュメントを作成する必要はありません。
（2）または（3）は、現在のストーリーの開発中は必要ありません。また、後続のいくつかの反復ではおそらく必要ありません。
また、チームメンバーがデザインドキュメントを書いたり更新したりするたびに、コードが作成されていないことにも注意してください。実際のコードの前にドキュメントを作成する場合、コーディングを開始するとデザインが常に変更されるため、ドキュメントを更新する必要がある可能性はほぼ100％です。コードの後に設計ドキュメントを書いても、私たちのチームが学んだように、後続のストーリーからのリファクタリングは依然として設計を変更します。
だから私がお勧めするもの：
- 最初に、一時的な設計/モデルを十分に作成して、コーディングの前にチームがインテリジェントな会話を行えるようにします。これらを保持することを期待したり、形式化に時間を浪費したりしないでください。
- 誰かが必要とする場合にのみ、公式の設計ドキュメントを作成します（つまり、チームには組織の記憶が本当に必要です）
- 安定化されたコードに関する設計ドキュメントのみを作成します。すべての反復で変更され続けるモジュールを文書化しようとしても意味がありません。
- モジュール（または製品の一部）を完全に説明する設計ドキュメントを作成します。過去には、私たちが行う必要のある変更を文書化した設計ドキュメントを作成していました。これらのドキュメントは、リリースが完了するとすぐに完全に価値がなくなりました。
- 文書を非常に高いレベルに保ちます。アーキテクチャと非常に高レベルのデザインをカバーする20ページを作成する場合、そのドキュメントはa）実際に他の人に読まれ、b）コードの一般的なレイアウトに慣れるのに役立ちます。詳細については、人々はコードに直接行くことができます。詳細な仕様の700ページを作成すると、ほとんどの場合、現実と一致しなくなります。だれでも読むには多すぎ、将来の変更が行われるたびに、20ページではなく700ページを維持および更新する必要があります。
アジャイルの「マントラ」は、完全にドキュメントなしで行うことではありません。
アジャイルマントラは、「 包括的なドキュメントよりも実用的なソフトウェア 」を優先することです。しかし、マニフェストの下部にあるビットに注意してください。
つまり、右側のアイテムには価値がありますが、左側のアイテムにはさらに価値があります。」
ボブおじさんには 文書化のための良いポリシー があります
必要が即時かつ重要である場合を除いて、ドキュメントを作成しません。
ドキュメントを作成しない言い訳としてアジャイルを使用する人もいますが、それは悪いアジャイルです。上記の引用で強調したビットは無視しています。
そうは言っても、「現在、新しい機能が「泥の大きなボール」システムの複数の領域に影響を与える可能性がある状況に直面している」と言った場合、アジャイルになる場合は、これについて何かする必要があります。
ドキュメントを入手したら、それを使用してコードをモジュール化します。このようにして、ドキュメントの長期的な必要性をなくすことで、ドキュメントを維持するための長期的な必要性（これは起こりません）を取り除きます。
すなわち。必要性を即時かつ重要なものにします。
不十分な要件について話すとき、最初に頭に浮かぶのは、テスト基準があることを確認することです。可能であれば、システムの既存の部分に対して再利用可能な自動テストケースをいくつか作成します。誰もがそれに慣れたら、コードを書く前にテストケースを書くことに移ります。優れたテストケースは、システムの動作を文書化するために多くのことができます。
使用する特定の設計ドキュメントについては、他の人がすでに述べたように、チームのニーズと彼らが引き受ける次のタスクが何であるかに大きく依存しています。可能であれば、使用するドキュメントを（コードから）生成できるツールを使用するか、ドキュメントからコードを生成してください。ドキュメンテーションのメンテナンスは非常に費用がかかる可能性があるため、設計ドキュメントを永続化する場合は賢明に選択してください。
個人的には、コードと適性テストケースから生成されたクラス図で大成功を収めています。チームはいくつかのクラス図を印刷し、製品所有者とマークアップセッションを行い、そこから見積もりを作成します。 Fitnesseに関する限り、私は幸運にも、スプレッドシートで必要なものを表現することに長けている2人の製品オーナーと協力して、それをFitnesse用のテーブルに変換しています。
アジャイルについての重要なことは、文書化の取り組みは実際にはスクラムチームによって推進されなければならないということです。開発者が外部ドキュメントがニーズに十分であると感じない場合、そうするまでユーザーストーリーはブロックされます。開発者が十分なドキュメントを作成していないと企業が感じた場合、製品の所有者はそれを許容基準の一部にすることを主張します。このため、スクラムに移行して以来、ドキュメントがより集中的で効果的であることがわかりました。
私たちは VersionOne を使用してユーザーストーリーを追跡していますが、私たちの方法は他のシステムにも適用できると確信しています。ユーザーストーリーにファイルを添付できます。設計書を置くのに非常に便利な場所であることがわかりました。
私たちにとって非常にうまく機能した1つの例として、プロトタイプを作成した後、できるだけ早く新しい回路基板の設計をテストする必要がありました。テストを必要とするすべてのものに対して2つのユーザーストーリーを作成しました。1つはテストの設計用、もう1つはテストの実行用です。設計ストーリーの許容基準の1つは、テスト手順が実行ストーリーに完全に文書化されていることでした。
テスト部分にたどり着くと、今まで見たよりもスムーズに進みました。ユーザーストーリーを開いて、ステップバイステップの手順に従いました。ドキュメントは、ストーリーを完成させるために必要なものであり、それ以上でもそれ以下でもありません。
他のチームが自分の製品を簡単に入手できるようにするために、使用するチップのドキュメントを改善するためだけに、バックログに別の話があります。
要約すると、ドキュメントに問題があると感じた場合、ソリューションは、個別のユーザーストーリーを作成したり、受け入れ基準の一部にすることと同じくらい簡単です。