Driving Agile Architecting with Cost and Risk

Eltjo R. Poort, IEEE Software, vol.31, no. 5, pp. 20-23, Sept.-Oct. 2014

Five pieces of advice can help architects become more effective in an agile world without having to implement new methods or frameworks. They describe changes in attitude or behavior rather than complete practices or principles so they’re easy to digest and apply.

Official link

Free version (Computing Now)

Pre-publication version

How DevOps impacts architecture

DevOps ArchitectureDevOps is an approach to IT that radically alters the traditional relationship between development, maintenance and operation of software. The traditional separation between Dev and Opsbrings with it a substantial amount of waste in terms of elapsed time and budget. This waste is caused by differences in way of working, attitude and hand-over inefficiencies. The waste is exacerbated by accountability mechanisms that incentivize Dev and Ops departments to erect barriers, to protect themselves in case the other side fails to fulfill its responsibilities (“cover your behind”).

In DevOps, this waste is largely eliminated by making one team responsible for both DEVelopment and OPerationS of applications. Supported by extensive automation (mostly by open source tooling) of testing and deployment, DevOps allows organizations like Facebook, Netflix and Google to deploy new releases into the Cloud on a daily basis. This is quite an improvement over the usual “once or twice a year” releases seen in traditional software products, and it gives organizations tremendous agility in reacting to market developments.

DevOps appears to be most successful in end-user facing (front-end) applications that run in public or private clouds and have a web-based user interface. The tooling supporting the approach is fascinating, especially in the way it ensures quality control: see Netflix’s Dianne Marsh take on this tooling at this year’s Saturn conference. But how does DevOps impact the architecture of the software that is developed with it? So far, I have found three ways in which DevOps influences architecture:

  • Architecting for deployability. Of all the quality attributes that a system may have, the one that is most directly related to DevOps is the ability to quickly deploy new releases into operation, with as much automation as possible. As I already mentioned in a previous blog, Stephany Bellomo and Rick Kazman of the SEI have made a study of this, and so has Len Bass of NICTA. An important consequence for architects appears to be the necessity to simplify and streamline the design. This includes standardization of infrastructure components, but also removing architectural elements which were originally intended to ensure other quality attributes, now overruled by the higher priority of deployability. One remarkable example of streamlining the SEI researchers found was the removal of an Enterprise Service Bus in one organization: originally implemented to enhance connectivity and modifiability, the ESB was found to be an obstacle to the speed of (automated) deployment and removed in the transition to DevOps (just an example – not a tip, ESBs generally have no quarrel with DevOps).
  • Architecting for systemic resilience. As the speed and scale of deployment increases, chances are that from time to time stuff (services, app, APIs) that your software depends on may not be available for a few minutes or hours. Your software needs to be able to cope with this: the system as a whole needs to still be as available as possible. Your particular piece of the solution needs to stay alive, even if the whole world turns against it. Organizations like Netflix harden their system (and I guess their developers!) by actually making things worse: their simian army of chaos monkeys, latency monkeys and so on wreak havoc in test and production(!) environments. As Netflix says, “the best defense against major unexpected failures is to fail often”.
  • Consolidated development architecture. In software development the target architecture for a solution has always put constraints on the set-up of the development environment, but with DevOps, it becomes almost impossible to see the development and operational environment as separate entities. From an architectural point of view, the development and target environments form one system with three main categories of users: developers, operators and end-users. One could even argue that that first two of those categories are the same in the DevOps philosophy. Many quality attributes affect all these user categories, and many architectural decisions have impact across the board as well. In DevOps, an architect (or “master builder”) does not design a target architecture after which an appropriate development toolset is selected: the whole ensemble forms one consolidated solution, with one solution architecture that addresses the combined architectural concerns for development and operation.

So as an architect, you may need to learn three new things: 1) to remove stuff rather than add stuff, 2) to design failure into your solution and 3) to design a consolidated development environment into your architecture. And you had better learn fast: Gartner calls this architectural approach “Web-scale IT”, and predicts that by 2017 50% of global enterprises will be using it.

What other aspects of architecture do you think is impacted by DevOps and Web-scale IT? Please leave your comments and let me know what I missed.

Impressions of SATURN 2014

SATURN (the Software Engineering Institute (SEI) Architecture Technology User Network (SATURN) Conference) has become my favorite annual professional event. What a great mix of architects, developers and researchers, and what a nice way to learn from each other.

The pervasive theme at this year’s SATURN was DevOps. Throughout the conference it became clear that DevOps is not just a hype-movement “taking agile to the next level”. DevOps will quickly become the standard way to produce a significant part of the world’s software. It is the only way to achieve real web-scale IT, supported by a high degree of automation – and by a strong architecture foundation to ensure qualities like reliability, availability and security.

The goodness started with Stephany Bellomo and Rick Kazman’s tutorial on the architectural foundations for achieving DevOps goals – most notably “deployability”. Stephany and Rick have looked into a number of cases to identify architectural strategies and tactics to decrease deployment time. They did not find any new techniques, but found that existing strategies often needed to be revisited to achieve DevOps goals. According to Stephany, DevOps forces architects to think about streamlining: removing stuff rather than adding. In some cases, this meant removing SOA components… which was ironic, since Stephany is one of the SEI’s leading SOA experts.

On Tuesday afternoon, I gave my own tutorial about Agile Solution Architecting. We had a nice crowd, which included OO design guru Rebecca Wirfs-Brock. Great discussions and feedback.

Wednesday had a nice keynote on refactoring by Bill Opdyke of JPMorgan Chase – some interesting points about making the business case for refactoring to your stakeholders reminded me of a previous blog post. In a session on Customer Collaboration, Samsung told us how they analyzed Twitter data to gather quality attribute requirements for their Galaxy model S5 – quite revealing. My presentation on the Costing View of Architecture was part of the afternoon’s Leadership and Business session.

The final session on Wednesday triggered some great discussion on fostering architecture communities in companies, which led to the creation of a LinkedIn group to allow the discussion to continue after the conference.

Thursday’s highlights were the two keynotes. Netflix’s Dianne Marsh told the story of the open source based tool stack supporting continuous delivery at Netflix. Very inspiring to see DevOps at work, although Dianne’s remark that she “never had to argue a business case or think much about cost” caused some of us to wonder whether successful DevOps implemenations were dependent on unlimited budget availability…

In the closing keynote, IBM’s Jerome Presenti gave us an awesome glimpse into the future. Jerome’s team develops cognitive systems, based on the IBM Watson system that won the Jeopardy quiz. It looks like the “Minds” in Iain M. Banks’s Culture novels are closer than we think… 🙂

On Friday, Rebecca Wirfs-Brock gave a tutorial on “Being Agile about System Qualities”. In terms of concepts, Rebecca’s had a lot of overlap with my own tutorial on Tuesday – but she explained them from the point of view of the agile mindset, which was quite enlightening. Architects can gain more traction with agile teams by being aware of their jargon (e.g. say “Design Spike” in stead of “Architectural Prototype”) and allergies (e.g. don’t use Powerpoint…). Perhaps we should stop using the A-word alltogether, and rather call ourselves “Master Builder” as suggested to me yesterday by a chief architect in a client organization…

All in all, a great week, many new ideas and new friends. Many thanks to all participants and organizers!

Edit (October 2014): you can now watch my Saturn talk (and most others as well) on YouTube:

Survey says… solution architecture works!

We all know that solution architecture adds value to business and IT solutions, but as Philippe Kruchten writes on his blog, we sometimes have trouble quantifying the benefits towards (project) managers or product owners. I recently ran into Raymond Slot’s PhD thesis titled “A method for valuing architecture-based businesstransformation and measuring the value of solutions architecture”, and was amazed by the resounding results he presents in it. Raymond did a thorough analysis of a survey of 49 software development projects between €50,000 and €2,500,000. He concludes that use of solution architecture correlates with the following effects:

  1. 19% decrease in project budget overrun
  2. Increased predictability of project budget planning, which decreases the percentage of projects with large budget overruns from 38% to 13%
  3. 40% decrease in project time overrun
  4. Increased customer satisfaction, with 0.5 to 1 point – on a scale of 1 to 5
  5. 10% increase of results delivered
  6. Increased technical fit of the project results

At first sight, these correlations already look pretty good, but if you read Raymond’s thesis, you see that the underlying numbers are even better. For example, the decrease in project budget overrun is presented as a percentage of the total budget. The expected overrun decreases from 22% to 3% – a factor 7 improvement!

The other results have equally interesting background data:

  • Better predictability of solution costing by a factor 3, specifically associated with the presence of an architect during calculation of the technical price, and with the quality of the solution (project) architecture.
  • The 40% decrease in project time overrun (c) is also much better than it looks, since it is stated as a percentage of project duration. Factors 6x-10x improvement of overrun are associated with the quality of the architecture and informal architecture compliance testing.
  • Increased customer satisfaction (d) is specifically associated with the quality of the architecture, and with matching the seniority level of the architect to the complexity of the project.
  • The increased technical fit (f) refers to better fulfillment of non-functional requirements, and is specifically associated with the quality of the project architecture.

In short, this research shows there are tremendous benefits to using solution architecture. The (b) effect in Raymond’s table represents a reduction of troubled projects by a factor 3. Together with the (a) effect, this result confirms the effectiveness of architecture as a risk- and cost-management discipline.

Thank you Raymond for helping us quantify the benefits side of the business case for solution architecture!


  1. Slot, R. (2010). A method for valuing architecture-based business transformation and measuring the value of solutions architecture (PhD Thesis). University of Amsterdam.
  2. Poort, E. R., & van Vliet, H. (2012). RCDA: Architecting as a Risk- and Cost Management Discipline. Journal of Systems and Software, 1995-2013.

The business case for technical debt reduction

When I teach solution architecture classes, technical debt is always a very popular topic among practicing architects. Technical debt is a metaphor that transposes the concepts of loan and interest to IT based solutions. It respresents work that should be done in order to deliver a consistent, maintainable solution. As long as the work has not been done, the solution is in debt, which means that some stakeholders pay interest in the form of e.g. extra effort needed for simple changes, or higher support fees. Repaying the loan’s principal means doing the work needed to remove the debt: this could mean e.g refactoring software or upgrading hardware. As soon as that work has been done, the stakeholders stop paying the interest, just like when a loan has been repayed.

Architectural debt

The technical debt metaphor has been very popular in the software development world, where it refers mainly to low code quality or unnecesary complexity. Tools like SONAR now have functionality that analyses source code to measure such “implementation debt”. For architects, however, other types of technical debt may be more interesting. Aside from implementation debt, there is “architectural debt”: this is typically structural in nature, or represents a technology gap.

esb td hi


An example of structural architectural debt is when an architectural principle like “all applications should use the Enterprise Service Bus (ESB) to exchange data” is temporarily violated. An architect could decide to allow direct access from application A to application B’s database if A needs data of B that have not yet been exposed through the ESB, and doing it properly would mean missing an important deadline. The interest in this case is caused by reduction of control of the information flow through the application landscape, and potential errors being introduced by teams that are not aware of the shortcut. The principal is the refactoring that needs to be done later on: changing applications A and B to route the data through the ESB, and configuring the ESB. This type of debt cannot be measured in the software code of either application: it is structural in nature. The same is true of technology debt,  when a solution uses obsolete hard- or software products that cause potential failures and risks (interest) and needs to be upgraded (principal).

Business case

One of the problems many architects face is convincing their stakeholders to reduce technical debt, mainly because the debt is invisible to the end-user (see Philippe Kruchten’s categorization). Making the case for technical debt reduction in technical terms will usually not convince the business stakeholders. That requires translation into economic terms – in other words, a business case.

If one has unlimited resources (time, budget, staff), the business case for repaying technical debt is quite simple: the longer you wait, the more interest you pay, so the economic optimum is immediate repayment. The only exception is when the solution is planned to be decommissioned, and the total interest to be paid over the remaining lifespan is lower than the cost of repayment. Usually, however, resources are limited and the business case for technical debt reduction needs to compete with other solution improvements, such as new features.

In all cases, proper representation of the interest is crucial to making a compelling case. In case of structural or technology debt, it is often hard to quantify the extra costs caused by the debt. The difficulty is compounded by the inherent uncertainty: things might go wrong, but they might also go smoothly, even with the technical debt present. One often hears arguments like “we’ve run this application on this platform for 15 years, and it has never caused us any problems – so why invest in an upgrade?”.

The risk factor

The key to making the business case for technical debt reduction is to account for the risk caused by the debt. The proper way to calculate the total expected cost of uncertain failure is the well-known risk exposure formula: E(S) = p(S) x C(S), where p(S) is the probability of failure scenario S occurring, and C(S) is the cost incurred when S occurs. By summing up the risk exposure E over all possible failure scenarios S caused by the technical debt, you come as close as statistically possible to an accurate prediction of the expected cost of failure.

I recently encountered a situation where a large transportation company was running some of their core business systems on ancient mini-computers. Spare parts were very hard to get by, and the manufacturer had put severe limitations on their maintenance contract. The organization in question had a hard time making the business case for migrating the system to a modern, virtualized, blade-based solution: the cost of the old platforms was so low that the ROI for the migration looked negative. The risk of failure, however, was substantial: a single missing spare part could potentially break the company by disabling their core system for a few days. Including that risk exposure in the technical debt interest leads to a completely different business case.

Forgetting the risk factor in the business case for technical debt reduction is a common mistake, which can lead to very wrong decisions. The organization in the example above instinctively knew they had to make the upgrade anyway, but the omission of the risk in the business case did lead to unnecesary delays in the decision making process.

In short: architects arguing for technical debt reduction should make sure that they articulate the risk component in the interest. This will help them convince stakeholders to give proper priority to things they might otherwise find less interesting for being invisible to end-users.

Architecture versus Design

In our architecture classes, we always spend some time discussing the difference between architecture and design. We say that architecture is a set of design decisions, so is there even a difference? In some domains, there really isn’t. In our organization, infrastructure architects generally take all infrastructure design decisions, and are responsible for the completeness of the design they deliver. Software architects sometimes leave detailed design to developers. Solution architects’ projects often encompass multiple technologies and domains, for which they cannot be expected to have mastered all the technology-specific skills to complete the detailed design work. Looking at architecture as a risk and cost management discipline (as RCDA does), the architect should focus on those design decisions that have the highest impact on the risk and cost associated with the solution.

When we ask architecture course attendants (most of whom are practicing architects) for their perception of the difference, a list similar to this one appears on the whiteboard:

Architecture Design
Fundamental properties Detailed properties
Define guidelines Use guidelines
Cross-cutting concerns Individual components
High-impact Details
Communicate with business stakeholders Communicate with developers

The table lists contrasting concepts, of which the one on the left is more generally associated with architecture, and the one on the right with design. The concepts are generally overlapping and not opposing. For example, some design details can have very much impact on the risk and cost of a solution, so an architect can never get away with just worrying about high-level stuff. Sometimes the devil is in the details, so the architect should look at some details – the trick is to know which ones. The fundamental properties come from the ISO 42010 definition of architecture. I think the bottom row is sort of wrong: architects should not communicate with business stakeholders more than with the delivery team, but sometimes it feels that way. The bottom row resonates with the distinction between Architectus Reloadus and Architectus Oryzus in Martin Fowler’s article “Who needs an architect?

The last few years, I have added two rows to the table:

Architecture Design
Manage uncertainty Avoid uncertainty
Conceptual integrity Completeness

The first of these is based on how we have seen typical architects and designers deal with uncertainty. When running into an item that has not been decided yet or is otherwise uncertain, successful designers usually put that item on the back-burner. They ask someone (a manager or architect) to resolve the issue, and then quickly move on to analyze the next use case or service item to keep up their productivity. Architects cannot afford to do that. Successful architects actively search for uncertainty, since uncertainty generally is associated with concerns with high impact on risk and cost, that need to be addressed as soon as possible.

The second additional contrast is Conceptual integrity versus Completeness. It pertains to the reason behind having two different roles for architecture and design. What is the main benefit of this role separation? When would you want to put one of the designers of a solution in a different role from the others, and call him architect? This only makes sense if it is too much work for one person to design the complete solution. If you need two or more persons to design a complete solution, it makes sense to appoint one of them to preserve the conceptual integrity across the whole solution. This person we call the architect, and the other designer(s)  should make sure that the solution design is complete. Looking at it that way, the distinction between architecture and design is a separation of concerns. The concerns of conceptual integrity on the one hand and completeness on the other hand need to be separated, because they would otherwise compete for the scarce resource of human attention, at the expense of either one or the other.

So if you are wondering whether your skills are better employed as an architect or as a designer, ask yourself this question: how do you like to deal with uncertainty? At the end of the day, do you get more satisfaction out of a) delivering a nicely rounded, complete design, or b) chasing down unresolved issues and making suboptimal decisions based on incomplete information? If your answer is a), you are probably better off as a designer than as an architect.

Architecture can be agile, too!

Ever since the introduction of “Agile” around the turn of the century, people have wondered how to combine agility with architecture. The difficulty of this combination is due in part to a fundamental difference in goals between the agile and architecture approaches: architects look for stability and future-proof-ness, while agilists want to embrace change, looking for a kind of future-“loose”-ness.

Some say architecture and agility are conflicting approaches. The agile proponents’ attitude towards Big Up-Front Design (BUFD) certainly seems to directly oppose the idea of architecture-driven development. This perception of conflict is increased by the agile movements’ tendency to behave like a religion, complete with dogmas and heretics, as wittily described by Philippe Kruchten. On blogs, agilists sometimes post rants against any suggestion towards up-front thinking about a solution’s architecture, or any hint that not all key (quality) requirements can be addressed afterwards by magically refactoring an IT solution. Fortunately, not all agilists scorn architecture, as witnessed by Scott Ambler’s essay on agile architecture.

Looking more closely, one sees that architecture and agility represent two ends on a spectrum.  Where in this spectrum is the optimal place for your project to live depends on the project context. As noted in an earlier blog post, Barry Boehm suggests that the ideal place on this spectrum depends on three factors that together determine the amount of architecture needed beforehand: the size of the project, the volatility of the environment and the business criticality of the solution.

Agilists can become more successful if they take the project context into account when assessing the usefulness of architecture, but what can architects do to cross the divide between agility and architecture? Judging by TOGAF, the Open Group’s popular architecture framework, the principles in the Agile Manifesto have long been neglected by the architecture community. ADM, the TOGAF architecture development method, still requires rather bulky documentation, produced by often heavy processes like Business Architecture, Information Systems Architecture and Technology Architecture. This type of enterprise architecture approach is not suitable for an agile environment. In the software architecture world, lighter architecture approaches like George Fairbanks’s “Just Enough Architecture” are gradually gaining ground. These more agile approaches no longer view architecting as mainly a design discipline, but also as a way to control risk and deal with uncertainty.

Risk- and Cost Driven Architecture (RCDA) is a relatively new approach in this arena. This approach was developed to close the gap between enterprise and software architecture. Existing software architecture practices are often too limited in scope for the solutions that need to be architected, but the enterprise architecture practices are too heavy for the agility required by time pressure and frequently occurring changes and uncertainty. The RCDA approach incorporates a number of aspects from agile software development practices, such as the use of a backlog of architectural concerns, to be frequently reprioritized based on economic factors like risk and cost.

arch workflow hiThe secret of making architecting agile is to change your view of the main deliverable of the work, just like with agile software development methods. An agile software development team does not deliver a “big-bang system”, but a continuous stream of improvements to a system. In the same way, an agile architect does not deliver a “big up-front design”, but a continuous stream of architectural decisions, step by step gaining control of the uncertainties and risks surrounding complex IT solutions. How much architecture to build in is determined not by agile dogmas like “You Ain’t Gonna Need It” (YAGNI), but by economic trade-offs taking into account the real value of architecture in context.

Architects can do much to cross the divide towards agility – in fact, they not only can, but must. If they don’t make this effort, architecture departments will lose touch with their IT development departments, where agile methods have become mainstream, and with their business stakeholders, who continually ask for faster and better responses to changing market requirements. The key change architects need to make is to no longer view architecture as a design document to be delivered to projects up-front, but as a continuous decision making process in order to gain control over cost, risks and uncertainty. Only then can architects deliver the added value and flexibility required from them by their business stakeholders.

Listen to Bett and Russ of architecturecast.net interviewing me about these ideas and RCDA.

What happened on Saturn

saturn-tutLast week, I had the priviledge of attending the Saturn 2013 conference in Minneapolis. Those who follow @eltjopoort on Twitter may have already seen some posts about it, but I thought I’d summarize the hightlights in this blog. SATURN is an important international architecture conference, organized annually by the Software Engineering Institute. It attracts an international audience of senior architecture professionals and thought leaders from all industries. All slides and summaries of the talks can be found on the SATURN conference website.

The first tutorial I attended was “Coaching architects” by Felix Bachmann on Monday. Felix talked about non-technical aspects of coaching or leading a group of architects, designers, lead-engineers etc. in a project. For me, the key take-away was his tip to “speed up the process of making mistakes” if you find people are slow to pick up your coaching. That way, people get quicker feedback and learn faster. Felix also repeatedly confirmed the RCDA principle that a leading or coaching architect is responsible for the architecture and the decisions that shape it, “even if the organisation says differently”.

On Tuesday, I gave a tutorial on RCDA’s principle of prioritizing architectural concerns by risk and cost. There was a lively interaction, and positive feedback from the attendants.

saturn-snowUp until Wednesday, we had had nice spring weather at >20 Celsius: then a rare May snow storm hit Minneapolis… fortunately, the Minnesotans had no trouble whatsoever dealing with that. The first keynote was by Stephan Murer, IT director at Credit Suisse. He presented the lessons learned of 15 years of SOA. Very interesting to see the lifecycle of this hyped technology summarized so nicely. Startling fact: it took 5 years (1998-2003) before the SOA services (CORBA-based) started to be used by more than a handful of applications – up till then, the business case for SOA at Credit Suisse was based on small gains from individual projects. Nowadays (2013), the application landscape completely depends on the SOA services exposing the company’s data, and the architecture has paid itself back multiple times. This story shows that long-term decision making is key in enterprise architecture. It also stresses the importance of a vision which may be based largely on belief in good design rather than demonstrable ROI. On the other hand, such a vision can only be sold to management if it is presented with economic arguments, or “you may have a short life as an architect”… Wednesday evening, I gave a lightning talk on assumption-free architecting, which according to the response from the audience was either quite funny or laughable…  see this previous post.

On Thursday, Simon Brown was the winner of the Architecture in Practice presentation award with his talk about the conflict between agile and architecture: myth or reality? (short answer: it’s a myth). Simon is a great presenter, and his award well-deserved. I’ll come back to my own presentation on lean and mean architecting in a later blog.

The closing keynote by Philippe Kruchten was very entertaining. Philippe discussed cognitive bias in architectural decision making; this seems to become an important theme in the architecture community. Philippe’s basis was Kahnemanns “Thinking – Fast and Slow”, a book about which I blogged earlier. Architects have to deal with a lot of cognitive bias, either unconsciously or consciously induced in reasoning fallacies and political games. He gave a long list of (often amusing) examples of how architects can make wrong decisions due to anchoring, confirmatory bias and availability bias. We have all run into  “Golden Hammer” (everything looks like a nail), “Elephant in the Room”, “Not Invented Here”, “Analysis Paralysis” and “Perfection or Bust”. Organizations often engage in architectural “Cargo Cult”, imitating the externally visible behaviour or architecture that appeared to work in another organization, hoping to achieve the same results – without verifying applicability of the underlying mechanisms in your context. Let’s kick our System 2 into gear!

utilization2On Friday, I attended two tutorials. Mary Poppendieck (LEAN high-priestess) taught us the LEAN mindset in a nutshell. I was amazed when she very simply demonstrated that optimizing a delivery organization for utilization inexorably leads to a substantial reduction of throughput! This effect from queueing theory starts at utilization over 50% if the batches of work are large. Powerful illustration: “Highways that are fully utilized are called parking lots”. I need to talk to management about our KPIs… J.

Finally, I attended Philippe Kruchten’s tutorial about roadmapping. RCDA’s Architectural Roadmapping practice is based on Philippe’s work, so there were no new insights for me – but we did have a lot of fun playing his Mission to Mars game.

All in all, a very enjoyable conference –presented RCDA, made new friends and learned a lot. Many thanks to all who made this possible.

Assumption-free architecture documentation

When reviewing architectures, I sometimes run into architecture description documents that contain long lists of assumptions. There are some negative connotations associated with assumptions. They often read as a “list of things other people should take care of.” They seem to imply that the author:

  • has not checked whether the assumptions are valid;
  • does not want any responsibility for the assumptions;
  • does not accept any blame if the assumptions do not hold;
  • avoids dealing with uncertainties.

It is better to avoid assumptions in architecture documentation: it is not coincidence that the RCDA Solution Definition template does not have a section called “assumptions”. There are several kinds of assumptions in architecture documentation, and they can usually be rephrased quite easily:

  • Scope limitation: “We assume that the client will take care of the network connection between the data centre and the Gouda office.” Rephrase: “The scope of the solution excludes network connectivity between DC and Gouda office.”
  • Interpretation: “We assume that a Spring/Hibernate framework on JBoss fits the client’s open source policy.” Rephrase: “Requirement RFP.OS1 Open Source is fulfilled by utilizing a Spring/Hibernate framework on JBoss. “
  • Dependency: “We assume that the PEAR application suite will run on a Websphere platform.” Rephrase: “There are no instances yet of PEAR application suite 4.5 running in production on a JBoss platform. Compatibility will be validated during the elaboration phase.”
  • Pending agreement: “We assume that the Testing Centre will  validate the performance criteria.” Rephrase: “The solution is based on cooperation with the Testing Centre for the validation of the performance criteria. Agreement about this cooperation is currently being negotiated by…., expected outcome October 15th at the latest.”
  • Pending decision: ”We assume that management will approve the necessary investment in the new Firewall “. Rephrase: “Management approval of the Firewall investment is expected November 10th. If it is not approved, the first three paragraphs of section 5.4 and figures 4, 5 and 6 of this document need to be revised.”

Care should be taken to place these rephrased assumptions in an appropriate section of the architecture documentation. Scope limitations and requirement interpretations belong in the Requirements section. Dependencies, pending agreements and decisions usually represent architectural concerns that have not yet been fully addressed, and belong in the Concern Register or equivalent section of the architecture document. Do not forget to document the implications of these. Many assumptions also lead to risks and may require mitigation measures, which should be added to the risk register and project plan.

Rephrasing assumptions this way has two clear benefits:

  • Clarifying what type of assumption we are making leads to more clarity what actions need to be taken to deal with them.
  • It avoids the negative “cover your behind” connotations many experience when reading assumptions, and gives a more pro-active impression of an architect who deals with, rather than avoids uncertainties.

What are your experiences with assumptions in architecture documentation? Are there more types of assumptions than the five categories listed above?