Avoiding the Icebergs

This article was originally published in VSJ, which is now part of Developer Fusion.
Today, the role of the software architect is widely recognised and most large system development projects are led by someone who takes particular responsibility for the system wide technical factors, such as ensuring that the system will provide the right set of qualities (such as functionality, availability, security and performance) for its stakeholders.

In recent years we’ve also seen a welcome increase in the number of resources available to the aspiring software architect, including useful books, community web sites and interesting blogs. However ultimately the success of a project is often found to be closely related to the amount of hard won experience that the project team has – by which we really mean how many mistakes they’ve learned from in their careers so far! Experience is a hard but very effective teacher.

In this short article I hope to share some of the pitfalls that I’ve encountered in my experience as a software architect and in so doing, help you to avoid making just the same mistakes on your projects!

(1) Scoping Woes

Many projects end up being doomed to failure before they’ve really started, simply because their scope was wrong. The most common problem is the infamous “scope creep” where the scope of the system steadily increases as more and more people get their say. This is the sort of situation where a simple travel booking system ends up with full expense claim management facilities being built into it, with inevitable repercussions for project costs, timescales and quality. The converse problem is where scope is artificially limited (perhaps to meet timescales) and so the effectiveness of the system is compromised. Architects need to maintain a particular focus on scope problems that relate to system qualities. Does the system really need to be available 24x7x365? Or would working hours plus Saturday mornings be sufficient? It is really true that no security is needed beyond simple login? Once logged into the system can users really perform any system operation? Catching these mistakes early in the project will help to greatly increase the probability of success.

(2) Not Casting Your Net Widely

A related mistake that many of us have made is to focus on just a couple of our system stakeholders – classically the acquirer (who is paying for the system) and the end users get all of the attention. However there are often quite a few other interested parties who need to be involved. Consider people like auditors, systems administrators and DBAs, testers, helpdesk staff, the development team and so on. You’ll probably need the cooperation of a fair number of these people in order to successfully deploy your system and number of them may not share your enthusiasm for it! Think about searching for stakeholders in groups like acquirers, assessors, communicators (like writers and trainers), developers, maintainers, suppliers, support staff, system administrators, testers and end users. The sooner you can make contact with these groups and understand their interests and concerns, the better.

(3) Just Focusing on Functions

It goes without saying that a key quality of a system is what it does. People buy or build systems in order to perform useful work and so it’s crucial that the system does what people need it to do. However, a trap that many new software architects fall into is focusing entirely on a system’s functions without considering any of its other properties.

Unfortunately, while we do need to get the system’s functional processing right, this is rarely enough; unless the system exhibits a whole range of qualities (such as performance, security, maintainability and so on) it is unlikely to be successful.

In my experience, an architect needs to focus on the type of functions that a system has to provide and must design a suitable framework that each of the individual features of the system can be slotted into during detailed design. The design of the overall framework has to take into account the kind of functions it will host (be they computationally intensive, data oriented, batch operations, interactive operations and so on) but crucially, it must also be capable of providing the right level of performance, allow the application to be secured, allow for high availability and disaster recovery, support operation and administration and so on.

In reality, if the system isn’t fast enough or is insecure, if it can’t be supported or changed to allow for new requirements, it probably won’t be used and may not even make it into production in the first place. Identifying and delivering on these non-functional requirements is a crucial part of the architect’s role.

(4) Box and Line Descriptions

At some point in the development of the system you will need to write something down to explain your ideas for the architecture of the system – in other words, you’ll need an architectural description.

The question is, how do you go about describing something as complex as a modern software intensive system? The approach that we’ve all tried at some point is the single, all inclusive, “boxes and lines” Visio diagram that tries to show everything. The diagram probably includes software modules and some interconnections, machines, network links, databases and data flow, some user interaction, perhaps some system monitoring and so on. If you’ve tried this yourself then you already know that it’s not a terribly effective approach.

There are two reasons why the huge Visio picture doesn’t work well as an architectural description: firstly, it’s trying to show too much information in a single representation, and secondly, no one is really sure quite what each of the different types of symbol that you’ve drawn mean.

The first problem means that the diagram doesn’t work well for anyone, as everyone has to hunt through it for the information they are interested in. Infra-structure experts have to discern the machines, network links and infra-structure software from the whole, software developers have to try to work out what the software layering is, testers need to try to untangle dependencies from data flows. Each person is mentally creating their own subset of the diagram in order to understand it. The solution to this problem is to decompose your large diagram into a number of well-defined, non-overlapping views of the system such that each view addresses one aspect of the system structure (such as runtime functional structure, software module structure, data structures or deployment environment). This is a well proven technique and there are a number of standard approaches you can use to guide you in achieving this (see the Further Reading section).

The solution to the problem of ambiguity is to make sure that you use a well defined notation for your diagrams and to provide enough supporting text somewhere to make your intentions clear. UML is an obvious starting point, given its tool support and wide use, although quite honestly it’s not a very good architectural notation (although again see the Further Reading section for some guidance on how to use it effectively). For those situations where UML isn’t effective, you will probably design your own notation to represent your ideas. However, remember to clearly define what your notation means so that people aren’t guessing – different people rarely guess the same way!

(5) Forgetting That It Needs to be Built

It’s always very satisfying to create and prototype an elegant, sophisticated design for a new system and it’s always more interesting if we manage to use some novel new technologies and techniques along the way. However, when we do this, it’s often worth asking ourselves which stakeholders our new design is really serving – the answer may well be ourselves, first and foremost (and possibly the development team).

I’m not suggesting that we shouldn’t innovate or that all systems should use COBOL and VSAM but always bear in mind that your design needs to be built, tested and deployed in order for it to be successful. If the design or the technologies you use are too sophisticated or immature, then you may be jeopardising this.

Common things to watch out for related to building the system include designs that the developers or testers don’t really understand, technologies that they aren’t enthusiastic about or don’t have the time to learn, and new technologies that don’t yet have good tool support or perhaps impose a new and unfamiliar way of working. The presence of any of these factors suggests that you need to tread carefully and make sure that you work with the development and test teams to minimise the risks.

Also bear in mind that your system needs to be installed, monitored and controlled in production. Sophisticated architectures can make all of this significantly harder and immature technologies often have weak monitoring and management facilities, even after their development support has been improved. Again, it’s a case of working with the relevant parties (such as system administrators and perhaps the vendors) to make sure that no one has any nasty surprises late in the day.


In this first part of the article, I’ve shared five of the pitfalls that have caused many software architects to come a cropper in the past. In the second part, we’ll examine five more that have proved to be equally problematic in their own way.

About the Author

Eoin Woods is a software and enterprise architect of UBS Investment Bank. He is a member and Fellow of the International Association of Software Architects, and will be speaking at IASA’s IT Architects Regional Conference in San Diego, Oct. 15–16 2007. He is also co-author of the book Software Systems Architecture: Working With Stakeholders Using Viewpoints and Perspectives (published by Addison-Wesley).


You might also like...



Why not write for us? Or you could submit an event or a user group in your area. Alternatively just tell us what you think!

Our tools

We've got automatic conversion tools to convert C# to VB.NET, VB.NET to C#. Also you can compress javascript and compress css and generate sql connection strings.

“Computer science education cannot make anybody an expert programmer any more than studying brushes and pigment can make somebody an expert painter” - Eric Raymond