I just finished a laborious, and somewhat exhaustive review of a relatively elaborate and extensive domain model with a set of business stakeholders last week. I know that a lot of upfront documentation is never considered a good thing on an agile project, but sometimes, when the scale of a project is incredibly large (think $20 million budget, and we inherited several thousand pages of requirements documentation before I came on board) it is necessary to capture business concepts in a form capable of providing effective guidance for future development.
The primary goal of this domain model was to take the vast ream of requirements given to us, and present them in a form that would be digestible by both business and developer/techie resources. In terms of total volume, the model consisted of approximately 16 diagrams, each describing a different domain concept, with approximately a page of text going along each diagram. In my opinion, this is not an awful lot of documentation compared to the source requirements we inherited which were thousands and thousands of pages long. When creating the domain model, we relied on many of the domain driven design approaches that can be found at http://www.domaindrivendesign.org/.
What exactly is the purpose of modeling?
While going over our models with business stakeholders, the biggest problem that I kept running into was that the client wished to see every single field and every single relationship on every class. They were under the impression that if the model wasn't perfect/complete it wasn't going to be useful. I did my best to explain that models did not need to be 100% perfect/complete in order to be useful, quite the contrary in fact. I'm not sure I did a perfect job in doing this, so I thought I would write up a quick blurb on what I believe are the primary purposes for modeling in the hopes that this will help me to defend my position better on in the future.
- Modeling enables Understanding
IMHO this is the most important part of modeling. Modeling enables people to understand what has gone on before their project, and also allows them to get a better understanding of what needs to happen next.
As an example of the "gone on before", take the all to typical situation where a developer team inherits requirements; sometimes of good quality, sometimes of not so good quality. Developers are asked to design or develop based on these requirements, and frequently don't even know where to start. Modeling and diagramming is an excellent way to comb through these artifacts and apply some critical thinking around them so as to make some initial directional setting decisions.
As an example of the "what needs to happen next", the same example also applies. The modeling done by developer type resources can also be used to apply critical thinking around what the data structures will look like, what the interface screens will look like, what services will be required, et cetera.
This modeling exercise is also the best way for these developer resources to actually understand any legacy documentation. Simply asking someone to read a pound of documentation will rarely result in comprehension of that documentation. Giving someone some documentation and asking them to perform a discrete activity will result in exponentially more understanding. Examples include reading requirements to do initial analysis/domain modeling, initial vendor analysis, usability/interface modeling, actual development, et cetera.
- Modeling Enables Communication
Simple models that abstract and structure a large amount of requirements (or any other system information for that matter) are worth their weight in gold. The maxim "a picture is worth a thousand words" is no truer than in the system development space. Being able to illustrate a vast and incredibly complex system with 10 to 20 pictures (or 1 or 2 depending on the level of abstraction) goes a long way toward ensuring that a lot of distributed teams have the same understanding of what the system needs to do.
So what does this have to do with my original clients desire to "have every field and every relationship described". You'll note that nowhere in these above two points did I mention "modeling to specify". Creating a specification means detailing every field, detailing every constraint, and every relationship, regardless of whether its fundamental to the point you are trying to make on a specific diagram or model. Creating a "complete" model actually makes it much more difficult to achieve the above two objectives. And here IMHO are the reasons why...
- Important concepts are obscured: if every relationship, every field, and every business constraint is modeled and presented how can we tell the important ones from the unimportant ones? A model that is too detailed has the unintended consequence of intermingling important concepts with unimportant concepts. The art of actually hiding unimportant information is crucial to creating good models, it's probably harder to create models that only display relevant information than to create models that show everything. But the result is certainly a better model, one that enables understanding of the system across a variety of stakeholders.
- The model is impossible to maintain: having been on several projects with a model oriented bent, I've had plenty of hands-on experience on the overhead required to maintaining readable and accurate models. In my experience, it is simply impossible to create maintainable models that are 100% precise down to the field level. At best, models are created that are "true when created" and get more and more irrelevant as time goes by. There are various experts out there who claim that modern tools make it easy to keep detailed diagrams and technical code in sync with each other. These experts need more actual hands-on practice with some of these tools, because this notion is still the stuff of ivory tower dreams, do not underestimate the effort involved in maintaining these types of models, it will equal, and often surpass your actual coding effort.
- Complete models are really just "code-umation”: code-umation” is documentation that approximate the detail level of actual code itself. This type of documentation is no easier to navigate than code, it is certainly harder to change than code, and is not executable or testable. Run, run, run as far away from this approach as you can. It doesn't matter if you're in sourcing, outsourcing, working on a large or small projects, this type of detailed documentation does nothing to help developers do their work, try picking up the phone, having a face-to-face conversation, or any other method to communicate detail of this nature. Better yet, follow some of the excellent implementation patterns found in Kent Beck's excellent text here to ensure that your code is readable and self-documenting.
- Drudgery versus innovation: creating detailed, field level, specification oriented models is mindnumbing, monotonous work. Good models are the result of critical thinking, innovative solutioning, and thoughtful analysis. These two styles of work are the opposite of each other. The more you focus on low-level details the less you'll focus on figuring out what the right things to do are, if you had the choice of receiving a high quality modeling backed by creative intelligent thinking or a complete model that was a result of monotonous repetitive effort what would you rather have. Don't ask for both, because it's simply not realistic.
So in short, when modeling, focus on what's important, focus on what you need to communicate, and focus modeling on helping you understand what you need to do next. In most cases the simple advice will go a long way in streamlining your modeling efforts in ensuring that your modeling and models stay relevant.