|
|
Sunday, February 01, 2009
|
There’s an old joke about an engineer called out of retirement by a company in trouble: their most vital machine has stopped working, and nothing they have tried will get it started again. The old engineer looks at the machine, studies it for a few minutes from different angles, and flips a switch. Presto! The machine starts to work, humming along like it never had a problem. The engineer hands the owner a bill for $10,000; and the owner says, “For flipping a switch? That’s outrageous! I’m not paying until I see an itemized bill.” So the engineer takes back the bill and writes on the back, “Flipping the switch: $1. Knowing which switch to flip: $9,999.”
Unfortunately, I find that a lot of patterns work is like that: if you know which pattern to apply, the work is (relatively) easy; but if you don’t know the patterns, you don’t know when to apply them. Like the company owner in the joke, there’s a switch out there, but you don’t know to flip it.
Well, the best way to learn patterns (like most things) is by experience. I can’t give you experience in a blog, but I can give you Diagnostic checklists that summarize experience. Patterns may also have Verification checklists, and Antipatterns may have Correction checklists. Some Patterns may have multiple Verification checklists. For example, Pattern 10. Brainstorming session has three checklists: one for preparing a Brainstorming session, a second for assessing the success of the session, and a third for summarizing the results of the session.
|
N/A: Your Defense Against Obsession
As I’ll discuss under Antipattern 26. Obsessive Compulsive Template Disorder (OCTD), it’s easy for bureaucracies to turn templates and checklists into must-do tools for “managing” a process, even when those templates or checklists don’t apply. This is a form of what Steve McConnell describes as “cargo cult software engineering”: going through the motions without understanding why, and without actually getting the benefits (Professional Software Development: Shorter Schedules, Higher Quality Products, More Successful Projects, Enhanced Careers, pp. 23-28.). These checklists aren’t goals in themselves; they’re tools to help you in your goal of more complete and useful requirements analysis.
The best defense against OCTD is N/A: Not Applicable. Whenever a line item in these checklists doesn’t apply to your project, mark it N/A. Then give your project 0 points or full points for that item, whichever you think is best.
Of course, it’s easy to take this too far, and mark everything as N/A. Perfection! You get 100%, right? Wrong. So when you do mark an item as N/A, also explain why it doesn’t apply to your project. If you can’t explain why, you can’t claim N/A.
|
|
Scoring the Checklists
Each checklist is scored on a 0 to 100 scale.
Diagnostic Checklists
Diagnostic Checklists are scored as follows:
0-20 Insignificant. This Pattern won’t help you much, or you have little risk of this Antipattern. Only worry about this Pattern or Antipattern if your project is mission-critical. Monetarily, this will cost you more than you’ll gain; but you could still mitigate non-monetary risks.
21-50 Minor. This Pattern may help you, or you have some risk of this Antipattern; but you probably have higher priority Patterns and Antipatterns to address. Worry about this Pattern or Antipattern if your organization is highly risk averse. Monetarily, this may cost you more than you’ll gain; but you could still minimize risks.
51-80 Significant. This Pattern will help you, or you have significant risk of this Antipattern. If you’re not addressing this Pattern or Antipattern in some fashion, that should be an item on your risk assessment.
81-90 Major. This Pattern should be a primary element of your requirements process, or this Antipattern is a primary risk for your project. If you’re not addressing this Pattern or Antipattern in some fashion, that should be a top item on your risk assessment.
91-100 Critical. This Pattern will be a critical element in the success or failure of your project; or this Antipattern is a critical risk for your project. If you’re not addressing this Pattern or Antipattern in some fashion, that should be an immediate item on your risk assessment.
|
Verification and Correction Checklists
Verification and Correction checklists are scored as follows:
0-20 Misleading. What you think you know regarding this Pattern or Antipattern is more wrong than right. If you proceed based on this score, expect to throw away and rework as much as 100% of your work.
21-50 High Risk. You’re starting to learn about this Pattern or Antipattern; but much of what you know is incomplete or incorrect. If you proceed based on this score, expect to throw away and rework as much as 50% of your work.
51-80 Agile. Agile processes are based on a conviction that many requirements can only be known through delivering and assessing code. Agile proponents point to examples and experience that show that requirements identified too completely in advance can be time-consuming and misleading. So an Agile team should aim for a middle-ground of knowledge: complete enough to lead to code, not so complete that they never get answers.
81-95 Optimal. Your knowledge regarding this Pattern or Antipattern is good enough for most teams to proceed. As Steve McConnell has documented (Professional Software Development: Shorter Schedules, Higher Quality Products, More Successful Projects, Enhanced Careers, pp. 15-16.), teams that focus on quality and defect reduction actually reduce costs and schedule by doing so, up to a point. After that point, even better knowledge costs more money and schedule, and is only appropriate for mission-critical projects. Most teams should proceed based on optimal knowledge.
96-100 Minimal Risk. Your knowledge regarding this Pattern or Antipattern is good enough for mission critical teams to proceed.
|
Point Lists
Point Lists apply to your entire requirements process. Each checked item scores a certain number of points. Check each item that applies, and sum the point points to get a score from 0 to 100.
Sample Point List: Feeding the Dog
□ 50 You have dog food; or you have table scraps.
□ 30 You have the dog.
□ 20 The dog is hungry.
____ Total
In some cases, the list potentially sums to greater than 100; but 100 is the maximum score in any case. For example, the Verification Checklist for Pattern 6, Trained Analysts, provides 100 points for dedicated analysts and 50 points for developers trained in analysis techniques; but a team with both still scores only 100 points.
Percentage Lists
Percentage Lists apply to your set of requirements, or perhaps to a set of one kind of requirement. Each requirement item is scored a 1 if it meets the criteria, or a 0 if it doesn’t (no partial credit allowed). Your score is the percentage of requirement items that scored 1 vs. the total number of items.
Sample Percentage List: Feeding the Dogs
%__ Percentage of all dogs which have been fed.
Partial Percentage Lists
Partial Percentage Lists are Percentage Lists that allow for partial points. Each requirement item receives some number of points based on various questions; and then you determine the percentages that meet different point scores. Full points count for full percentage; but the percentage of partial points are divided to yield a lower score. The final score is the sum of these adjusted percentages.
Sample Partial Percentage List: Caring for the Dogs
□ 1 The dog is fed.
□ 1 The dog is groomed.
□ 1 The dog is exercised.
%__ Percentage of dogs which score 3 out of 3.
%__/2 Percentage of dogs which score 2 out of 3.
%____ Total
Diagnostic Checklist: Requirements Archaeology
□ 70 Your project is to supplement, upgrade, or replace an existing system.
□ 30 The existing system is poorly documented, or the documentation is out of date.
____ Total
You can learn how to score the checklists here.
|
Problem:
The project is to supplement, upgrade, or replace an existing system, which is the de facto primary source of your requirements.
Context:
In many organizations, new work has to be done in a context of legacy systems, which embody a wide range of explicit and implicit requirements that customers may overlook.
Forces:
- Legacy systems represent an investment of capital and time that must be conserved.
- Legacy systems may not be well documented or well understood by the current customer.
- The team that built the legacy system may no longer work in this organization.
|
|
Legacy systems represent an investment of capital and time that must be conserved.
|
|
Solution:
Reverse engineer models (see the Modeling pattern) and specs for the current system, and review those to identify requirements. Then analyze and organize those “uncovered” requirements, and present your results back to your customer as a form of The Echo Effect. Be ready for your customer to be surprised, as you reveal features they’ve long forgotten, never known about, or just taken for granted. Listen for them to identify legacy features that they don’t need replicated or supported, and then explore those features to be sure there’s nothing there that other features depend upon.
|
|
You may be able to rely on mechanical tools to do much of this reverse engineering. Many UML tools, for example, will reverse engineer models from source or from compiled code.[1] Other tools will reverse engineer and graphically depict database schemas, network layouts, and other elements of existing systems. |
But you need to go beyond such mechanical reverse engineering for two reasons.
- It’s far too coarse, as our archaeology metaphor shows. Imagine the look on an archaeologist’s face if a contractor showed up at a dig site and said, “Hey, I’ll dig up this whole excavation for you. Let me get my bulldozer.” While mechanical reverse engineering isn’t destructive like the bulldozer, it’s not much more discriminating. The bulldozer piles up a great big heap of earth and stone and rubble, while the mechanical tools pile up a great big heap of classes, relations, tables, columns, nodes, and other artifacts. If you don’t sift through the rubble, you really haven’t learned anything.
- In my UML classes, I teach that UML isn’t about software design, but rather about system design, where a system is structure with behavior and goals. Well, I’m missing something in that definition: a system is structure with behavior that fulfills some intention. A good mechanical reverse engineering tool should produce a structural model of a legacy system. Modern tools shed a little light on the behavior model of a system. But only a human reader can produce “intentional” models. A mechanical model captures Functional Requirements at best; but an intentional model captures the User Requirements, Business Requirements, Non-Functional Requirements, Constraints, Actors, and Domain Objects that are represented by the Functional Requirements. (See the Categorization pattern for a discussion of these types of requirements.)
|
So certainly start with mechanical reverse engineering, as much as your tools will allow; but then dig into the resulting models and organize them (a form of The Outline Effect) to learn what’s in the models. From there, you can create behavioral and intentional models by looking at mechanical models, the user manuals, and the system in operation and then deducing how these fit together.
Resulting Context:
The reverse engineered requirements should serve as a baseline for or input into the requirements for the new system or extensions to the existing system. From there, turn to other patterns as a way to elicit and analyze new requirements.
|
|
Certainly start with mechanical reverse engineering, as much as your tools will allow; but then dig into the resulting models and organize them (a form of The Outline Effect) to learn what’s in the models.
|
|
There must be new requirements, right? You’re not just replacing the existing system for something to do, right? There should be some reason for replacing it: porting to a new platform, better maintainability, better extensibility, or something. If you’re just suffering from replacement-itis, you should read Joel Spolsky’s essay on rewriting.He makes a good argument for preserving the hard-earned knowledge embodied in legacy systems, and the consequences of replacing working code without a business case.
Discussion:
See also Modeling, The Outline Effect, and The Echo Effect for patterns that work well with Requirements Archaeology.
Verification Checklist: Requirements Archaeology
For each pre-existing system or component:
□ 1 You have a mechanically reverse-engineered structural model of the component.
□ 2 You have a manually reverse-engineered intentional model of the component.
□ 1 You have a presented one or both models to the Customer and received useful feedback.
%__ Percentage of requirements which score 4.
%__/2 Percentage of requirements which score 3.
%__/4 Percentage of requirements which score 2.
%____ Total
You can learn how to score the checklists here.
|
|