24/04/2008 by Jon.

This post is part of a series based on the book Documenting Software Architectures: Views and Beyond.

We are on to page 18 now for those keeping track of these things.

The core of the approach set out in the book is the use of viewpoints. This is that when we try to describe a system it is simply not possible, or even desirable to, to do this in just one way. The leap that we as architects need to make is to ensure that what we put down in writing addresses the need of the reader, not the writer.

To use the bus analogy (see Is it a bird Is it a building? No! It’s a bus!), what the maintenance team are interested in is not the same as the accountant. There may well be some common ground, say in on-going costs, but they are looking at the same solution from very different perspectives. I’m guessing here, having not read the whole book yet, that the key is to have a commonly agreed and standardised viewpoints. Having these pre-agreed means that the architects know what to produce and the stakeholders know what to expect. This is not as easy as it sounds in the real world. It is not uncommon to find that there is some standard defined, but that it is not sufficiently explicit or even worse no examples are available.

“Every project has to produce this document”.

“Can I see an example then?”

“Er.. no”

“Then what about all the previous projects? What did they do?”

Silence.

Sounds like madness, but I’ve been there. Back to the book. hopefully the use of the industrial strength documentation standards will start to address this problem.

Posted in Views and Beyond | Print | No Comments »

02/04/2008 by Jon.

This post is part of a series based on the book Documenting Software Architectures: Views and Beyond.

One of the first sections (page xix) is about the picture on the front cover which shows a rather nice sketch of a birds wing. The section discusses the use of analogies and our usual staple of the “building” to help describe architecture. I am as guilty as anyone in using this as a way of explaining what I do. Yes, I do think about the structure of the system/building. No, I don’t worry too much about the colour of the screen background/carpet (apologies to any HCI specialists reading this, I do know that colour on a UI is important but hopefully you get my point).

The authors quite rightly point out that buildings are fundamentally static objects while systems and fundamentally dynamic. In fact most systems fail in their dynamic behaviour rather than their static structure. Hence the use of a birds wing which has a complex dynamic model is a far better analogy for architecture than the building. An excellent insight!

But somehow it wasn’t satisfying as an analogy. For the front cover of a book by architects, for architects, it works well. However when I tried to visualise myself standing in front of a group of business managers talking about bird wings it felt wrong. These people are fundamentally pragmatic and practical. If I start talking about hummingbirds I’m going to lose them. So what would be a good analogy?

Now I come from an engineering background so naturally started thinking about engines and alike. Again this failed the “audience empathy” test. Your average business person doesn’t care much for thermodynamics or metal fatigue. So I tried a little bigger. A car? Better on the empathy test but didn’t feel very business relevant. Then I struck on an idea. What about a bus? They are fundamentally about engineering which is good; we want to be based on good engineering practices. There are dynamic and static elements so it addresses the shortcomings of the building analogy. It has business users (the driver) as well as customers (the passengers). There are business owners (the fleet operator) and a support organisation (the maintenance team). Importantly it also meets the “audience empathy” test. We all know what a bus is, it is a common point of reference.

Now before we get too excited it is just an analogy. A useful way of getting understanding between different groups. This does not represent the birth of a new design method based on route planning and seat colours, but it might just help a little.

So I haven’t even reached the preface to the book and already the authors are making me think, even changing the tools of my job. While I will be using a different approach to theirs, this exercise has made me question what I do. I call that a good start, although at this rate it’s going to take me a long while to read this book!

Posted in Views and Beyond, How to Architect | Print | 1 Comment »

28/03/2008 by Jon.

Following on from my earlier post The Trouble with Documentation I went off and bought the SEI book by Paul Clements et al. I’m now working my way through the book with the intention of applying much of what it says. My hope is that this will help to kill off, or at least calm down, some of the on-going arguments that always seem to ensue. How detailed is high level design? What should we put in the design documentation? So how long is this design work going to take?

If the blurb on the back cover is anything to go by then help is at hand. I’m just hoping that the book can deliver on the promise.

I’m going to try and blog some of the interesting points I come across, mainly so that I don’t forget them, but also to explore them a little more. I’m not going to reproduce the book, that would be both illegal and rather pointless, but I do want to dig around some of the key ideas. I like to think that I’m a fairly practical architect, in that I work on projects with customers the whole time. Having tried out many approaches and techniques over the years I often find that while the theory is great the rigour tends to tail off when you get down to the practicalities. Given the authors and heritage of this book I’m hopeful this won’t happen.

To be continued….

This post is part of a series based on the book Documenting Software Architectures: Views and Beyond.

Posted in Views and Beyond, How to Architect | Print | No Comments »