Geeks With Blogs

  • UMLGuy @LeeHate are you still selling art? I would like to license Vodun Bokor for book/ebook cover. It's incredible! You're very talented. about 958 days ago
  • UMLGuy @kzoomoo Indeed. You know 2 of my influences. Characters have multiple influences, but Father and Daughter partly inspired by your family. about 1344 days ago
  • UMLGuy @SteveAndrews That is awesome news, man! You worked hard for that. about 1345 days ago
  • UMLGuy The Night We Flushed the Old Town in Digital SF V2. Kindle: It's about ecological disaster. And beer. about 1360 days ago
  • UMLGuy @kzoomoo Sounds like a very happy birthday! Your kids are great, as always. about 1495 days ago
  • UMLGuy @julielerman You're in Bangalore and Bali... and you need cheap tickets to feel lucky? I would call that great fortune in itself. about 1495 days ago
  • UMLGuy So weird watching Dr. Gregory House M.D. play Bertie Wooster. Same facial expressions convey completely different meanings. about 1495 days ago

News LoungeWare is now available. The UML Guy T-Shirt
Ulterior Motive Lounge UML Comics and more from Martin L. Shoemaker (The UML Guy),
Offering UML Instruction and Consulting for your projects and teams.

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.


The project is to supplement, upgrade, or replace an existing system, which is the de facto primary source of your requirements.


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.


  • 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.


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.

UML tools that will reverse engineer UML structure include ArgoUML, Enterprise Architect, IBM Rational UML tools, and MacA&D, among others. In their preview of the 2010 version of Visual Studio Team System, Microsoft has demonstrated powerful UML tools, including the ability to reverse engineer sequence diagrams from source code. This is a major advance in general purpose reverse engineering, turning what used to be hours of manual work into minutes.

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.

  1. 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.
  2. 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.


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.

Posted on Sunday, February 1, 2009 1:13 PM VSTS 2010 (Codename Rosario) , Requirements Patterns and Antipatterns | Back to top

Comments on this post: Pattern 19. Requirements Archaeology

No comments posted yet.
Your comment:
 (will show your gravatar)

Copyright © Martin L. Shoemaker | Powered by: | Join free