Documentation

Let's start to _model_ our software architecture!

As architect, you are often reminded that you should model your architecture and not just draw diagrams. But have you ever seen a real architecture model?

I’ve only seen some aspects modeled, not the whole architecture. I use Sparx Enterprise Architect now for aprox. 15 years, but still don’t know how to use it the right way and really model my architecture.

why model and not just draw?

But let’s first start with the basic question why we should model and not just draw. The results often look the same. And what do I mean by “model”?

I remember a good example which I have read in a book, but I can’t remember which one. (if you know where I have stolen it, please contact me :-)

Imagine, you have a sports car.

Now imagine you have a small replica of this sports car. This is your model.

It might not be like the real thing, but certain aspects are accurate. In this example, often the look is accurate but the engine won’t work.

That reminds me of the quote “All models are wrong, but some are useful” by George Box. So wether your model is an exact replica which you put on the shelve in your living room or it is a toy car with which your kids play - these models are useful and make sense for a certain use case, but an engineer might complain that it is wrong in terms of the engine details.

Now imagine you have a detailed replica and you take some photos:

  • One of the outside view and one of the view from the driver’s seat. These might be great picture if you want to sell your car.

  • One of the motor and one of the bottom of the car. These might be great pictures for a mechanic.

These pictures are the views onto your model.

You also could have drawn those views, but as you can see, it makes more sense to first create the model and then the views.

It is the same with software architecture. Think about it!

PS: in this example, it would have been even easier to take the pictures from the original sports car. But that does only work if your already have the finished product… https://structurizr.com/ by Simon Brown takes this approach.

First appeared February 5, 2018 on rdmueller.github.io