|Please contact us for more information
Precision Quality Software, Inc.
Context Diagrams: An Explanation
When a doctor analyzes a patient's health, then the more information, the better. Nevertheless, doctors often use X-rays, which actually hide various types of information, about skin, muscle and so on. Why would anyone use an information-obscuring tool so as to obtain more information?
Part of the answer is: sometimes, the problem is too much information: the sheer volume of it becomes overwhelming. That is one of the reasons why, in medical practice, X-rays add value. They obscure some aspects and thus make it possible to focus on other aspects.
The analogy applies to requirements engineering. Often, the amount of information is so overwhelming that it's difficult to make sense of it all.
Yes, Details are Important, but …
There's a special irony: many requirements engineers and developers are very detail-oriented, able to juggle vast complexities. This ability helps them win the battles, but it may yet cause them to lose the war, by overlooking large items. Often, these omissions are noticed so late in the project that including them requires a massive amount of rework.
Telling a requirements engineer "Remember, don't overlook any large items," is not helpful. Often the oversight occurs in spite of a diligent attempt to identify hidden issues. This is where context diagrams can save a project from some very nasty surprises. Ironically, context diagrams can often be performed with a very minimal investment of time, yet they can prevent many hours of frustrating interactions that inevitably follow the discovery of a large item that was overlooked. Creating context diagrams is a fairly interesting and pleasant task whereas scope-related interaction is typically highly unpleasant, especially because it so often implies massive amounts of rework, schedule slippage, budget overruns and so on.
For the same reasons smoke detectors and seat belts are a good idea, context diagrams are a wise investment of time. Essentially, they constitute cheap but high-coverage insurance. No, you're not guaranteed a positive return on investment, but chances are good that your additional half-day spent on context diagramming will, in the long run, more than pay for itself even if you just focus on your hours as a requirements engineer. When you focus on the time invested by the project team as a whole, context diagrams become more palatable yet, because scope issues often involve many high-level players sending angry emails and trying to shift the blame to others.
Hamburger A or Hamburger B?
A decade or so ago, Wendy's restaurants had a wonderful series of television advertisements in which a pleasant, reasonable-seeming interviewer would present someone with two choices: a delicious-looking hamburger (hamburger A) from Wendy's or a rather sad-looking hamburger (hamburger B) from some anonymous competitor. Of course, the rational interviewee would choose hamburger A without hesitation, but what made the ads funny was the total absence of rational interviewees.
For example one interviewee chose hamburger B and explained that he had been raised to always be second-best and not aspire to the best things in life. The set of ads showed a variety of silly interviewees, each of them choosing hamburger B. Perhaps the funniest part of the ad was the astounded expression on the face of the interviewer.
In the spirit of those advertisements, we would like to present the options in a similar way:
Option|| Task of Requirements Engineer ||Task of Senior Stakeholders||Expect to Hear: |
Process A||Spend perhaps a day's worth of interesting, creative work, drawing a context diagram and involving the senior stakeholders to obtain their input.||Spend an hour or two per person, reviewing, discussing and pondering the context diagram.||I'm glad you caught this. I totally missed it.|
I'm starting to see the value in your structured approach. Bravo!
You're right - if we're going to include this extra functionality, we'd better ask for more budget and time.
Process B||Spend many hours, spread over many miserable days, with a schedule interrupted by phone calls and short-notice meetings, trying to explain to a set of hostile senior management participants why a particular issue was not included in the scope. Each of them has 20/20 hindsight and the ability to make any reasonable situation seem ridiculous.||Spend many hours, spread over many days, defending themselves from management attacks and trying to find a politically vulnerable person on which to blame the situation.||I don't see how you guys could have overlooked this. My memo, two months before, clearly stated…|
This omission is so big you could drive a truck through it.
No wonder people are saying you guys can't program your way out of a wet paper bag.
We strongly recommend you choose Process A.
So, What IS a Context Diagram?
A context diagram is a data flow diagram, with only one massive central process that subsumes everything inside the scope of the system. It shows how the system will receive and send data flows to the external entities involved. Here's a theoretical example:
And Data Flow Diagrams are …?
Data flow diagrams, in their simplest form, show that a data flow occurs -- somehow, sometimes, for whatever reason. They don't show when it occurs, or under which circumstances, or using which medium. Like an X-ray, the data flow diagram focuses only on a few important essentials. At a level of granularity where there's a danger of entirely overlooking a data flow, a data flow diagram is a good start.
Data Flow Diagramming Methodology
Two common symbol sets are used in data flow diagramming: Gane-Sarson and Yourdon-De Marco. Both provide adequate means of expressing the concepts. Please, please don't try to invent yet one more methodology: requirements engineering is already confusing enough.
The following diagram shows a Gane-Sarson example, to indicate that Person A communicates the customer name, and the agents then store it in the customer file:
The following diagram shows a Yourdon-DeMarco example:
Symbols Used on Diagrams
At PQS, we happen to use Gane-Sarson symbology. As such:
The agents or operators who perform the work are considered "inside the process," and as such are not shown. Fortunately, for context diagrams, you don't have to worry about data stores. They're considered internal to the process.
- processes are shown as squares with rounded corners (which in this example happen to be colored red)
- external entities (the people with whom the process interacts) are shown as squares (which in this example happen to be colored blue)
- data stores are shown as elongated, flat rectangles (which in this example happen to be colored green)
- data flows are shown as arrows
If You're Still not Convinced …
Imagine you're in charge of a big project to develop software to administer the many interactions involved in employee health and safety (EHS) training, at a company that manufactures electronic components using dangerous chemicals and high-voltage equipment. Your project is going well. You've just rolled out the first version and the users love it.
Suddenly, a disgruntled EHS manager comes out of the woodwork and asks why the system doesn't produce the various reports mandated by OSHA. He explains that it annually costs the company hundreds of contractor man-hours to compile the data and generate the reports, and all of the data seems to be in your system. You promise to investigate. There's no budget for this investigation and it somehow didn't seem appropriate to ask for funding, and you're not sure how to account for your time, doing this investigation. As it turns out, the reports are complex in their implications. Being an experienced requirements engineer, you notice that there is a subtle but vital difference in the way that the report uses a particular concept ("employee") and the way that your system uses it. To the casual observer, it looks like the data could simply be pulled out of the system to make the report, but this would result in precise yet misleading data. Changing the way that your system treats the concept of "employee" would at this time require a massive rewrite. Had you been aware of the report as being a requirement, you'd have approached the issues differently, but it's too late now.
You report back to the EHS manager, and you're not surprised when he reacts very negatively. The issue soon escalates up the organizational chart. Your system, so deserving of victory inside the scope for which it was intended, is suddenly and unfairly mocked as a classic example of poor planning.
No, it's not fair - but it could have been prevented quite easily. As you discussed the context diagram with the senior stakeholders, someone might have remarked, "Oh yeah, we also deal with OSHA. We send them some reports." At that point, the sequence of events would typically have resulted in the OSHA reports being either ...
... thus enabling you to tell the EHS manager "Yep, we generate these reports automatically now" or "no, the senior stakeholders (managers X, Y and Z) all agreed to keep the OSHA reports outside the scope of this project. Please talk to them for the reasoning behind that decision."
- Clearly inside the scope of the system, or
- Clearly outside the scope of the system