The dos and don’ts of modeling
Recently I was asked to talk about modeling with our developers. What does modeling really mean? And how should you approach modeling? And how can you learn how to read models?
Prolog
In one of my previous jobs, I was a newly hired IT architect at mid size telecom company. Before this I had been programming and creating software solutions for about 15 years, but this was my first job as a “real architect”. One of the first things that ended up in my lap was this huge information model that a consultant had made for the company a year earlier. This model was really huge and it was all on just one page! And it contained these strange arrows that I had never seen before. I had to print it out in A3 size to be able to read the text and get the overview at the same time. I spent months (even years?) trying to get into this model, and really understand its implications.
About the same time, I was asked to create a systems overview of the IT architecture. Inspired by that big information model, I decided to crank it all into the same picture. I mean, that must be the way since you get both details and overview at the same time? I had multiple workshops with people who knew the details and spent weeks composing it all into one huge system model. I was really proud and felt like a real architect! When I presented the model, people looked a bit overwhelmed but I thought that it was normal and that they would learn how to read the model.
Back to the information model that I had been given before. When I finally had some really clever questions and really needed some answers, I called the consultant who had made the model and asked him. And he didn’t know the answers, because the model was too complex even for him. He actually started suggesting that the model needed to be expanded even more. That’s when I realized that there must be a better way.
Don’t crank everything into the same picture!
The problem with those big one-page models is that the only person who will ever understand them is the architect who made it. If you ever want someone else to understand your models, you need to break them up into smaller pieces. A good way to do this is to think about Resolution, Perspective and Target audience.
The idea here is that different people have different needs, and the models are created to meet those needs (they are not created just because an architect need to have something to do). If we take the Pointy Haired Boss, he will need something on a high level without too much detail (resolution), probably oriented around thing that cost (perspective), while our friend Alice the Project Manager need more details about things that need to be done and things that affect others. Dilbert the Developer needs the most detail since he will be implementing the system.
One person who realized this a long time ago was John A. Zachman. He made up his own framework called the Zachman framework. Although the Zachman framework is valuable, I believe that it is too complex for most situations. In my experience, the following Zachman “Light” approach covers most needs.
The idea with a framework like this is that you can choose what cell you want to create a model for. That model will be valuable to people who have the matching needs.
Let’s explain the framework by using an example. The classic Pet Store!
Let’s say that we are developing a web shop for the Pet Store. How would the models in each framework cell look?
Pet Store Models
Information domains
Resolution: Overview
Perspective: Information
Target audience: Everybody
The purpose of this model is to give a brief overview of the domain objects that are relevant to the business. It could also serve as a starting page for further drill down into the information models. The model does not conform to any formal modeling language.
Information domain model
Resolution: Specific
Perspective: Information
Target audience: Project management, team leads
In this area I chose to draw two different models, one ER model and one Concept model. I think both these modeling languages are very powerful, but have slightly different usages. The strength of the ER model is to explain the relationships between the domain objects, in terms of “one-to-one”, “one-to-many” and “many-to-many” relationships.
On the other hand, the Concept model is handy for describing more verbal relations such as “an Owner has a Pet” and “a Cat is a Pet”. Both of these modeling languages are easy to learn and are thus great tools to use in workshops with non-techy people.
Information class diagram
Resolution: Detailed
Perspective: Information
Target audience: Developers
The class diagram is almost as detailed as the programming code and may or may not be helpful. Once you get down to this level of detail, you need to be careful to not over do it, since the model may be obsolete very fast.
But I still think this is a valuable tool, especially when you want to explain something to someone else and it’s too complex to just look at the code.
A note about the modeling language UML. I have certainly struggled over the years to understand UML since it has a very different terminology than the one used when programming in an object oriented language. For example, when a programmer talks about Inheritance, the corresponding UML term is Generalization. I guess this is something we have to live with until someone invents a new modeling language that is more closely related to programming concepts.
System Context View
Resolution: Overview
Perspective: System
Target audience: Everybody
In this model, the objective is simply to place our target system on a map to see what relevant neighbours it has. What user groups it has, and what other systems it communicates with.
System Containers View
Resolution: Specific
Perspective: System
Target audience: Project management, team leads, developers
The purpose of this model is to drill down into the system and specify its major building blocks and how they relate to each other. The term Container is used since these are the building blocks that contain the code that we are going to develop.
Don’t get too technical here, it is more important to understand the relationships and information flow between the containers, than to worry about protocols and port numbers.
System Components View
Resolution: Detailed
Perspective: System
Target audience: Developers
In this model, we have drilled down into one of the containers in the previous model to show its most important parts. So what is a component then? Well, it is of course depending on what technology you are using, but if it’s Java or C# I would say that a component is a group of classes within a package/namespace, with a well defined interface in front. A component should have a purpose and it should be able to fulfil the tasks given to it. The arrows in the component view illustrates the direction of the method calls, which directly corresponds to the dependency order of the components.
Process Overview
Resolution: Overview
Perspective: Process
Target audience: Everybody
Here’s another high level model, this one represents the core process of the business that we are supporting, i.e. the Pet Store. It really looks like some kind of management fluff, and it is. But it can actually be useful as a starting point for understanding what people actually do in the business, and in what order.
Process Workflow
Resolution: Specific
Perspective: Process
Target audience: Project management, team leads, developers, UX
In this model, we have drilled down into the Sell Pets process in the overview and started to describe how we present our product to the user in the web shop, how the user picks a pet to buy and how she proceeds to perform the purchase. This model could be a great input to the UX team, since they are the ones that should detail the look&feel of each screen, and make sure that it has a logical and user friendly flow. Actually, it may very well be that the UX team draws this model to describe the flow to the development team.
Sequence Diagram
Resolution: Detailed
Perspective: Process
Target audience: Developers
This model is closely related to the Container and Component diagrams, but with a time perspective, and the purpose is to describe how the Containers or Components communicate in order to solve a specific task. In this example we have come to the Checkout flow where the customer purchase the pet and the system converts the purchase into an order in our ERP system. It also sends a confirmation email to the customer.
Conclusion
Now we have seen how a business and a system can be described by drawing several different models with different perspective and resolution. You may find that some of them are really useful, and some are not so useful. Which ones you use are really up to you. I certainly have my favourites! I hope that having read this article, you will find it a little bit easier to decide what type of model you should create in order to communicate just the thing you have been thinking of.
Further reading
I can truly recommend that you read the book Software Architecture for Developers by Simon Brown. It’s a real down-to-earth book about things that most developers care about. The Context, Containers and Components model that I use in the System perspective all come from this book.
