Value-driven Architecture Documentation

“[We value] working software over comprehensive documentation” features proudly on the front page of the Agile Manifesto. Further down on the page, the authors explain that they do not mean that there is no value in documentation (just less value than in the working software). The practice of documenting architectures in particular has significant positive correlations to solution success factors like predictability, customer satisfaction and technical fit. So we should not abandon the practice of architecture documentation, but we should document our architectures in a way that yields optimum business value.

Bloated architecture documentation

In the past few years, I have helped many organizations modernize their architecture way of working. At the start of these endeavors, the average architecture documents are usually quite large – 200 pages is not abnormal. The templates alone often contain dozens of pages. It didn’t use to be like that – when they started out documenting architectures 15 years or so ago, the templates were nice and small, and focused on a limited number of views, designed to show how a key set of stakeholder concerns had been addressed (such as Philippe Kruchten’s 4+1 Views). However, over the years new insights led to new sections to be added to the template. Concerns that led to business risks or disruptions required new views, such as a Security view or an Integration view. The emerging realization that architecture is a set of design decisions led to the addition of new ‘Architectural decisions’ sections. Outsourcing part of the development sometimes required yet again more detailed views.

The Architecture Document had become the single repository for all architectural knowledge related to a product. This is not a problem per se, except that these same documents were used to show stakeholders that their concerns were addressed by the architecture. Specifically, they were the vehicle for obtaining approval from business owners. Business stakeholders were expected to read, understand and approve hundreds of pages of architecture documentation. Naturally, this led to delays: the architects would spend more and more time preparing the document, and the approvers would take more and more time approving them. Leaving blank parts ‘to be completed later’ did not help, because it increased uncertainty in the stakeholders about the completeness of what they were approving. Documentation bloat had caused the architectural feedback loop to become longer and longer, and caused significant delays when starting up new initiatives.

The value of architecture documentation

It is not surprising that documentation bloat causes organizations to start questioning the added value of architecture documentation: perhaps that value is lower than the cost of the delays the document causes. So let’s see if we can answer this question: “Why were we doing this again?”

In the organizations I work with, I see three main purposes for architecture documentation. We are communicating the architecture to show stakeholders how their concerns are addressed, often in stakeholder-specific views, but also to involve them in the architectural decision process (driving the architectural feedback loop). Additionally, we are communicating the architecture “to the future” for various purposes – let’s call this architectural knowledge preservation. This leads to three distinct business goals for architecture documentation:

  • Explain how stakeholder concerns are addressed (including business, DEV and OPS)
  • Preserve architectural knowledge (for analysis, realization, trouble-shooting,…)
  • Collaborate on architectural decision making

Each of these business goals has manifest business value, e.g. in terms of decision support, driving progress, design quality, risk and cost control.

Separate according to purpose

When we look at the audiences and timing of the three business goals identified above, we quickly see that they require very different language and rhythms in order to provide optimum value:

The insight that the language and timing requirements of these purposes are so different helps us understand that the ideal of “one document as the single repository of architectural knowledge” is not viable. If we want our business stakeholders to quickly grasp that their budget and delivery concerns are addressed, we should not send them a 200 page document and then ask their approval. If we want the development teams to easily learn how to implement our architecture, we should not bother them with exhaustive lists of business rationale behind all the underlying decisions (we should not hide that rationale from them either: sometimes it is needed to make the right development choices).  

The picture above is an example of how to separate the various rhythms and languages of architecture documentation.


The insights above have helped us to significantly reduce the size of the architecture documents presented to stakeholders. In one organization this helped reduce the start-up time of smaller projects from (typically) two months to two weeks – a real boost to agility and benefit to the organization.

Move slow and fix things

Four years ago, Facebook changed its famous motto “Move fast and break things” to “Move fast with stable infra” (not quite as catchy?). Most people associate the original motto with disrupting established business models (see e.g. Jonathan Taplin’s book with the same name). Mark Zuckerberg himself, however, hinted that its origins lie in a particular attitude towards software engineering: “As developers, moving quickly was so important, we would even tolerate a few bugs to do it”. As time goes on, this attitude apparently does more harm than good – as even Facebook found out.


“Move fast and break things”, in software engineering, signifies the need to quickly create functionality in the beginning of a product life cycle. It is related to the first agile principle: “Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.” Functionality represents direct business value, and the “break things” part of the motto assigns lower priority to work that represents indirect business value, often called ‘enablers’.

Agile principles eight and nine, however, stress the importance of sustainable development and technical excellence, and the ability to “maintain a constant pace indefinitely”. Enablers create and maintain the architectural backbone of a product and safeguard long-term quality. An organization that neglects enablers in favor of functionality builds up technical debt; the longer enablers are postponed, the higher the debt and its impact on productivity and quality. A product or organization in technical debt cannot maintain a constant pace indefinitely.

All of the large organizations I encounter in my daily work are struggling with a burden of technical debt in one way or another. In many cases, the pressure to “move fast” has led to underfunding of enablers like ‘under the hood’ improvements and technical debt reduction. They have moved fast, and now things are broken.

How did we get here?

Discussions with architects, product owners and managers reveal some potential causes for the technical debt burden:

  • ‘Regular’ modern business practices: KPIs (Key Performance Indicators) often lead to prioritizing short-term, measurable success over long-term investments.
  • Overinflated stakeholder expectations: temporarily postponing enablers (often for good business reasons) leads to a steep growth in business value, delighting stakeholders. Teams then become reluctant to break the news that they cannot maintain this pace, forcing themselves to keep it up and build up more debt.
  • Cargo cult: the success of Internet giants prompts organizations to adopt their methods, practices and frameworks without properly considering the differences in culture and business model (and when the methods fail, their proponents call for even more extreme implementations, because “we must have been doing it wrong” of “we were sabotaged by non-believers”).
  • Misapplication of specific agile practices, such as:
    • WSJF (Weighted Shorted Job First) prioritization (specific to SAFe, the Scaled Agile Framework): due to their size and indirect business value, enablers generally cannot compete with features and functionality in WSJF prioritization. This is why SAFe advises to allocate capacity for enablers separately; ignoring this advice leads to misapplication of WSJF to enablers, and build-up of technical debt.
    • MVP (Minimum Viable Product): an initial product with just enough features to satisfy early customers, and to provide feedback for future development. It is in the nature of MVPs to ignore ‘edge cases’ (rarely occurring uses of the product) and some non-functional requirements (NFRs, e.g. limited scalability). However, edge cases and NFRs can have major impact on the architecture. Continuing development based on an MVP without properly considering (or completely rebuilding) the architecture is a misapplication of the MVP practice that leads to build-up of technical debt.

Product evolution based on a Minimum Viable Product may require rebuilding the architecture

The road ahead

During the panel discussion on the “Death of the Architect” at this year’s SATURN conference, I joked that the world is drowning in a pool of technical debt. That was a bit overdramatic, but nobody can deny that we have a problem. Not only is the technical debt burden draining businesses’ resources away from their ability to innovate, it is also causing real problems in society – that is how dependent we have become on properly working software. Architectures that do not support edge cases can even have significant ethical implications by excluding groups of clients and citizens from (sometimes essential) services (a number of cases like this are documented extensively in the Kafka Brigade’s ‘The Digital Cage’, currently only available in Dutch).

Technical debt causes real economic, societal and ethical problems. It is time we did something about it – starting by addressing the root causes mentioned above. I do not have the illusion that we can easily change the short-term focus in modern business governance practices, but we can certainly be more transparent in managing stakeholder expectations about sustainable development. We can also be smarter in applying agile practices – most of which is making sure we understand the practices and their limitations before we apply them.

Paying more attention to enablers means there will be less capacity for new things – initially, we will slow down. But maybe that’s a good thing. Grady Booch recently tweeted the question “What does software development look like in a post-agile world?” I hope we will slow down and fix things.

Opportunity Cost in the Technical Debt Business Case

A few years back, I discussed the business case for reducing technical debt, and the importance of accounting for the risk exposure in that business case. However, there is another item in that business case that deserves some attention: the opportunity cost, defined by The New Oxford American Dictionary  as “the loss of potential gain from other alternatives when one alternative is chosen.”

When a Dev team spends resources and time on reducing technical debt (upgrading, refactoring, repairing), the team will produce fewer end-user stories during that time. Opportunity cost represents the business value that those end-user stories would have yielded, as a way of accounting for the scarcity of the team’s resources.

The literal term ‘opportunity cost’ is seldom heard during technical debt discussions, but it is often a major factor in deciding when to reduce the debt. Whenever a stakeholder (e.g. a product manager) says something like “Yes, we should do something about this debt, but we cannot afford to do it now”, she is probably referring to the business features that end-users are waiting for, or that have been promised before a certain deadline. In other words, the opportunity cost of reducing the technical debt – the potential gain from the alternative of delivering the business features on time – is higher than the interest on the technical debt incurred during that period.

The figure is an attempt to illustrate the opportunity cost by comparing two scenarios: in scenario 1, the technical debt is not payed back, and in scenario 2, the debt is payed back in release 1.2. The value curve at the top of the figure makes a little dip in scenario 2 (dashed line), compared to the continued growth of scenario 1. Using Philppe Kruchten’s backlog color coding, the figure shows that in scenario 1, release 1.2 introduces five new (green) user stories, while in scenario 2, there is only time for one user story because we have spent the rest of the resources on reducing the (black) technical debt. The gap between the dashed and the solid line represents the opportunity cost of reducing the technical debt. (In case you are wondering why the dashed line goes down in release 1.2, even though we are adding a user story: I always feel that existing business features in a solution are subject to some kind of value decay, due to growing expectations and demands from end-users – debatable I know, but beside the point of this blog post).


A good example of opportunity cost in architectural technical debt reduction was presented to me by attendants of an RCDA Practitioner Course a few months back. In their organization, a team had been developing business process automation features for 4 years. The organization had kept track of the labor cost savings attributed to that automation effort, which amounted to 9 FTE (full time equivalent positions) per year on average. The platform the software was running on was due for a major overhaul, because it could not easily be made compliant with new European Commission regulations (most notably GDPR). During the overhaul, they would not be able to develop new features – meaning an opportunity cost equivalent to 9 FTE per year, or 0.75 FTE per month spent exclusively on the overhaul. A significant opportunity cost, but it was determined that the risk of non-compliance outweighed the opportunity cost, in favor of the overhaul.

In conclusion: if you need to draw up a complete business case for taking care of a piece of technical debt, make sure you include the opportunity cost on the costs side. This will help to facilitate a rational discussion about the impact of delaying features, putting this (architectural) choice in its business context. And while you’re at it, don’t forget to include the reduced risk exposure on the benefits side!

What happened on SATURN 2018

The annual SATURN conference is usually one of the highlights of my professional year, and SATURN 2018 was no exception. This year’s edition took place in Plano, TX, and presented another jam-packed cornucopia of digital architectural knowledge in four parallel tracks over four days. Don’t be sad if you’ve missed it: all sessions have been recorded and will be posted to the SATURN playlist on YouTube. I will certainly check back there to see some of the talks I had to miss – because there was just too much going on in the parallell tracks..


Monday was warming-up day with full-day training sessions and a workshop on “growing great designers”. I attended the workhop, in which we discussed how to select and train designers and architects – but also how to get organizations to care about good design. It was interesting to brainstorm the essential “canon of knowledge” about software design, which made us realize that the paradigm of architecture as a set of design decisions is still not as accessible as we would like: there are great books and established training curricula about many other design paradigms, such as patterns, modeling and many architectural styles – but if someone asks “How do I put the idea of architecture as a risk-driven decision making discipline in practice?”, there’s no easy answer yet (although George Fairbanks’ “Just Enough Software Architecture” comes close, as does the RCDA training program). The workshop outcome can be found on github.


The conference proper took off with a keynote on evolutionary architecture by Rebecca Parsons of ThoughtWorks. She introduced the idea of an “Architectural fitness function” to describe how close an architecture is to its desired characteristics. Measuring the function over time would enable us to monitor architectural quality during an architecture’s evolution. Extending quality attribute scenarios with temporal behaviour?

In the afternoon, we played the Smart Decisions Game – a fun way to introduce people to the idea of making architectural trade-offs based on quality attribute requirements. The task was to select machine learning algorithms for a specific context, and we each received a deck of cards. Each card summarized an architectural choice (an algorithm), including its impact on quality attributes. The game was extremely well prepared by the guys from SoftServe and Rick Kazman. and I was especially impressed by the ease with which we could plug these algorithms into their toolbox.

We closed the day with a nice reception, playing quaint folklore games like Cornhole and the bizarre Armadillo races…


Wednesday’s keynote by Ricardo Valerdi was a fascinating journey into the world of Virtual Reality. Ricardo told the story of the development of an app for creating concussion awareness among football players. It was a nice bridge between architecture and user experience, which becomes ever more important as an architectual concern.

Michael Keeling then presented a very practical (as always) lesson on managing technical debt.

I was especially happy to see Thijmen de Gooijer expanding on the metaphor of marriage for committing to architectural decisions which I had introduced a year earlier in my talk on architecture life cycles. Thijmen had some great examples. Trying out compatibility with a potential mate by making a trip to IKEA is a bit like setting up a continuous delivery pipeline – the only way to the exit passes by everything you could possibly run into, and if you have seen your mate’s reaction to all that is on display you get a pretty good idea of what life with that person will be like…

In the afternoon, I talked about Shortening the architectural feedback loop – an extended version of my blog post with the same name. We had nice discussions, and this talk was voted runner-up for the best presentation award. [edit: watch the talk on the SEI YouTube channel].

Death of the architect

After my talk, there was an amusing panel discussion about what’s happening to the role of software architect and how teams should make important crosscutting design decisions, called “Death of the architect”. The general consensus seemed to be that it is a good thing that architecture is becoming more of a shared concern than the domain of a single person – however, the pendulum seems to have swung too far in the direction of decentral decision making, to the point where people don’t care about design anymore, or even refer to architecture as “the dark side”. This excessive denial of the importance of cross-cutting coherence has led to a worrying build-up of technical debt across many organizations, with some disastrous consequences. This prompted the remark that “If the architect is dead, the world is doomed: it will drown in a pool of techncial debt.”

The other highlight of the afternoon was a nice talk by Sebastian von Conrad, about applying the concepts of Douglas Hubbard’s “How to measure anything” to quality attribute quantification.


The final day started with an amusing game of slide roulette (a lot of fun, but why schedule it at 9AM???), after which Linda Northrop Award winner Eoin Woods gave a very nice acceptance keynote, describing the Five Ages of software architecture, and his outlook for the coming age of “Dissolving systems”.

After two interesting GDPR-related talks by David Max and Andrzej Knafel, it was time for the Ethical Software Architect workshop that I had prepared with Michael Keeling. [edit: watch the session on the SEI YouTube channel]. We looked at some examples of ethical impact of architectural decisions in news headlines, and at some reasoning frameworks architects can use when they are confronted with ethical dilemmas. We then split up in groups to discuss fictitious scenarios that any architect could sooner or later encounter. These discussions became so lively that we got some complaints from jealous speakers in neighboring rooms afterwards! The attendants were so happy with this session that they voted it number 1 for this year’s best presentation award – which says a lot about how architects feel about ethical aspects of their work. There seems to be a real need for more ethical guidance for architects in the digital world, and I would be surprised if it wouldn’t become a regular topic in architecture conferences the coming years.

The closing keynote was by Michael Nygard, famous for best seller “Release It!“, a book about building software that survives the real world. Michael philosophized a bit about various categories of coupling between modules and systems: Operational Coupling (Consumer cannot run without the provider), Development Coupling (Changes in producer and consumer must be
coordinated), Semantic Coupling (Change together because of shared concepts), Functional Coupling (Change together because of shared responsibility) and Incidental Coupling (Change together for no good reason). These musings reminded the “elderly” among us of work done in the 70s and 80s about modularity and the birth of object orientation, but it was nice to see these design fundamentals expressed anew by someone who has great impact on modern views of software engineering management.


All in all, the conference left me feeling very fulfilled and inspired (and not just because of the nice recognition I received from the attendants’ rating of my sessions).


Next year: Pittsburgh!




Architecture is Context

For architects designing complex solutions, a well-documented set of requirements can never be the sole basis of the architecture. Architects have to undestand why these specific requirements are relevant to their stakeholders, and most likely will have to ask “why?” again and again to understand the stakeholders’ real needs, so as to design the architecture that best fulfills those needs and the goals behind them.  When talking to architects about their work, I often summarize this principle as “Architecture is Context”.

The importance of context

What makes it so important for architects to understand the wider context of their solution? When we view architecture as a set of design decisions, a good measure of a decision’s architectural significance is the economic impact of that decision on the collective stakeholders affected by it (see RCDA: Architecting as a Risk- and Cost Management Discipline). So in order for architects to understand the significance of their decisions, they need to have a firm grasp of the economic context of the solution they are architecting.

A second reason architects need to understand context and background is because requirements (especially non-functional or quality attribute requirements) often turn out to cause conflicts in design decisions: for example, making certain company data available in a mobile app may be good for  productivity, but bad for security.  Architects can only make these types of trade-offs if they not only know the requirements, but also fully understand the business and technology drivers behind them (asking your stakeholders to prioritize NFRs doesn’t really help, since this quickly becomes a meaningless exercise if it is done separate from the design – see Issues Dealing with Non-Functional Requirements across the Contractual Divide).

Flavors of context

A complex solution has many types of stakeholders, each of which have their own goals and needs, contributing to the integral solution context. When focusing on economic impact, the first thing that comes to mind is the business context defined by the business stakeholders, who pay for or benefit from the solution. Architectural significance, however, is determined by a much wider range of stakeholders. Examples are operational and delivery stakeholders, for whom we need to understand the technology and project/release context, and citizens affected by the solution’s safety, security and privacy context.

Understanding context

What can architects do to improve their understanding of a solution’s context, and design architectures that better fit their stakeholders’ underlying needs?

  • Talk to stakeholders. Architects who talk to their stakeholders get a better understanding of their context – well duh, talk about kicking in an open door. And yet… I still run into architects that are so focused on documentation, or on a particular subset of stakeholders, that they forget to interact with the rest. This goes both ways: being too exclusively focused on your technical stakeholders (“architects must code!”) is as bad as only being interested in “the business” side of things. Make sure you speak your stakeholders’ language – watch Jochem Schulenklopper’s SATURN 2015 talk “Why they just don’t get it” if you want to know how. Without actually talking to stakeholders, my other two tips (modeling context and trace decisions to context) lose most of their value.
  • Example of a system context diagram

    Modeling context. Modeling system context has been part of software design methodologies since the early days. In the 70s, the Yourdon Structured Design method involved a context diagram, which showed which external systems and users interacted with a system – a technique many (including me) still consider essential for clarifying the solution boundary and external dependencies. In fact, the first C in Simon Brown’s C4 model stands for Context, represented by just such a context diagram. UML’s use case diagrams fulfill a similar role (but much less clearly). Michael Jackson’s problem frames go a step further by modeling not just physical and logical context of the system itself, but also the wider context needed to understand the design problem to be solved.

  • Trace design decisions to context. Once we have gone to all the trouble of understanding the context of the solution we are architecting, it is paramount that we record the impact of that understanding on our architecture. The perfect place to do that is in the ‘rationale’ section of our architectural decision record. Here is where we show that our decision is based on something in the real world, real concerns, goals or other drivers from our stakeholders. This not only helps us get buy-in for the decision, but also brings huge benefits if the context changes (or should I say “when the context changes”, because it usually does). If we have to revisit an architectural decision, knowing the full context of the original decision rationale makes re-appraising the trade-offs much easier. Putting it in economic terms, tracing your architectural decisions to their context lowers the cost of change – making your architecture more agile.

In conclusion, context is key in architecture, and there are several ways in which architects can improve their understanding of context and its impact. The most important tip is to talk to your stakeholders, and keep asking them “why?”. What is your take on this? Do you always draw a context diagram? How much context do you put in your architectural decision records?



Shortening the architectural feedback loop

One of the things architects can learn from the Agile mindset is the importance of short feedback loops. The quicker an architect receives feedback on their output, the faster they learn about its effect in their specific solution context – and better informed architects make better decisions. Architecture is a matter of reducing uncertainty by gathering knowledge and making decisions, and a shorter architecture feedback loop speeds up that uncertainty reduction, leading to better architectures. On top of this, shorter loops lead to shorter reaction times when things change, which increases agility. In this blog post, I will share some tips for shortening the architectural feedback loop.

Architectural decisions are your primary deliverable

What does your organization consider the primary architectural deliverable? Chances are it is a document with a name like Project (Start) Architecture or Software Architecture Description – let’s call it The Architecture Document. It takes weeks or even months to produce, after which time all architectural models and decisions are approved and distributed in one foul swoop – The Architecture Document version 1.0. If you are in this situation, the first step to shortening your feedback loop is to start viewing individual architectural decisions as your primary deliverable. The finer granularity of these decisions, compared to The Architecture Document, will make it much easier to speed up the feedback loop.

Continuously share concerns and decisions

Do not be afraid to share your unfinished architecture output. The sooner you share, the faster you learn. I like to let my stakeholders (both business and technical) know what I think are the most critical architectural concerns, and share decisions as soon as I am aware that they need to be taken. (One word of caution: always make sure the status of the decision-in-progress is absolutely clear to prevent people acting on them prematurely.) This gives stakeholders the opportunity to contribute to the architectural process from the start. Make this information as easy as possible to access: don’t put it in text documents, but find a low-threshold platform like a Wiki or issue tracking system.

Invite immediate feedback from stakeholders

We are often hesitant to ask for feedback on something that we ourselves do not consider to be perfect already. Architects, however, cannot afford to wait that long. Most architectures emerge from a dynamic process of frequently identifying new concerns, repeatedly finding out new facts and continuously adjusting partial decisions that interact with each other and our context. The perfect architecture is only known after the solution has been delivered (if then).

So tell your stakeholders to give you feedback when they have it, and not to wait for ‘official’ review moments like a ‘version 0.9’. Make it as easy as possible for them: enable the comments box on your Wiki, invite people to email you. If big print-outs of your architectural models adorn the team’s war-room, make sure to put a pencil on a string next to them. Make sure everyone knows you welcome feedback by asking for it at the water cooler, or on your team chat platform if you are not co-located.

Simplify your architecture documentation template

Template bloat is one of the causes of long architectural feedback loops. Organizations often lack a decent repository for architectural knowledge, and abuse their architecture documentation templates as a dumping place for all lessons learned. Diverse stakeholder concerns for all types of solutions end up getting their own sections in the template. On top of that, architects for whom The Architecture Document is the only place to store knowledge about a solution cause even more bloat. There are two things you can do to fight this document obesity:

  • Create a template with sections for only the most common concerns at only the start of a solution’s lifecycle. Get rid of all ‘placeholder’ sections. Add views for other concerns only as they become significant later in the lifecycle, and only insofar as they are relevant to your context – in short, create living, minimal architecture documentation.
  • Make sure you have another repository for knowledge that is not immediately relevant at the current point in the solution lifecycle. Create a wiki or library for the organization’s lessons learned and documentation plug-ins for views to be added later in the lifecycle, and find a place outside of The Architecture Document for solution-specific insights that you have gathered.

Get involved in delivery

The final tip for an effective, short feedback loop is to get involved in the delivery of your solution. If you are a software architect, coding key parts of the solution yourself is a great way to get involved. If you do not have that opportunity, get involved in integration, quality attribute testing or other architecturally significant delivery activities. You will not only become your own feedback channel, but also stimulate other delivery team members to tell you about their concerns and help improve your architecture.

In my work of coaching organizations to approach architecting in an agile way, shortening the architectural feedback loop has proven to be one of the most effective ways to improve architects’ effectivity and business value. Especially its positive effect on the scability of architecture work and the start-up time of smaller projects is quickly noticed and appreciated by business stakeholders. Let me know if the five tips in this post prove to be useful to you as well.


Another great SATURN (SEI Architecture Technology User Network) Conference in Denver last week. The cast of interesting and directly applicable topics was led by two main characters: microservices and event sourcing. Apart from those leading roles, there were supporting roles for functional programming, and of course the popular returning role for good old uncle agile architecture. Below is a day-by-day account, with links to the video recordings for each of the sessions discussed.

Tuesday: details and crowdsourcing architecture

A great start with a keynote from @KevlinHenney, stressing the need for attention to details – even (or especially!) for architects. As Edsger Dijkstra wrote, “The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise.” Sometimes architects hide behind the “architecture as an abstraction” definition as an excuse not to go into details. However, sometimes the devil is in the details, meaning a tiny detail may have substantial risk and cost impact – meaning it is architecturally significant (according to Risk and Cost Driven Architecture).

The highest impact speaker this year was undoubtedly Sebastian @vonConrad, whose first session had some great tips about being an influential architect among 23 fully autonomous teams. If you have no decision authority, influence the decision makers (in the teams). And people are most likely to be influenceable when you help them. Sebastian did this by setting up an architecture guild, facilitating inter-team knowledge sharing and peer reviews based on very light-weight architecture documentation for projects (“project docs”) and architectural vision (“light on the hill”). Especially his approach for setting technology standards without stymieing innovations (“sensible defaults”) was refreshing. (I unfortunately had to miss Sebastian’s second session on event sourcing because it coincided with my own session on architecture life cycles – but I will certainly watch the recording once it is published.) Later that day, Stefan Toth (@st_toth) spoke about more or less the same topic under the title “the distributed architect”. Stefan presented a very nice model to decide how “crowd-sourced” your architecture can afford to be, with four levels of central roles: fully crowd-sourced (no architect), architecture marshalls, an architecture owner or the classic architect.

Wednesday: microservices and functional programming

This year’s highlight in terms of usefulness to me was Chris Richardson’s (@crichardson) keynote “There’s no such thing as a microservice“. I have seldom seen one of the field’s rockstars explain a concept so clearly, pragmatically and especially objectively.

Architectures are made to fulfill quality attributes. The quality attributes a microservices architecture is optimized for are all related to development velocity. The price you pay for this velocity is complexity – and it’s not cheap. Making the microservices themselves loosely coupled and simple means that all the remaining essential (coordination) complexity will end up in the surrounding architecture. Chris then went on to introduce his pattern language – a set of architectural tactics meant to address this complexity concern. The most interesting of these patterns was event sourcing, a tactic to avoid microservices having to access common data or using two-phase commits on transactions (often required by business logic). Chris also gave a very pragmatic rule for optimizing the size of a service in a microservices architecture (because “there’s no such thing as an individual microservice”):

  • small enough to be delivered by a small team
  • big enough to have meaningful business functionality

George Fairbanks (@GHFairbanks), one of SATURN’s organizers, won this year’s new directions award for his talk on functional programming, which appears to be coming back in fashion (remember LISP?). George explored the ramifications of this programming paradigm on the architectural level, in a fun way (which included a marbles game).

At the end of the day, I presented at a very interactive session in which we went looking for the common ground between architecting in an agile versus more traditional, project-governed context. Organizations sometimes can be rather sensitive about the words they use to describe elements of architecture work (e.g., “is the solution defined in a project intake form, an epic or a saga?”). In order to stay away from this loaded terminology, I used the metaphor of a human lifetime to analyze how architectural activities and decisions evolve over a solution’s life cycle. I am considering using the response I got in that session to write a little dictionary to help translate between “agilese” and “projectese” language…

Thursday: event storming and architectural decision records

The final conference day started with @RuthMalan‘s acceptance speech for winning this year’s Linda Northrop Software Architecture award. My successor made a passionate plea for visualizing designs that should be based on objective reasoning.

After a hilarious bout of slide roulette, I attended @ThePaulRayner‘s session on event storming, a workshop form for soliciting requirements from stakeholders built on the concept of events (rather than business objects) as the primary entity. It resonated nicely with my plea for time as a first-class citizen in architectural design. Paul’s method seems to be mainly focused on business scenarios, it would be nice to try it out as a way of soliciting change scenarios for architecture roadmapping.

Later, @michaelkeeling gave a nice report of his work introducing architectural decision records (ADRs) in his team at IBM Watson. He observed that modules that have documented ADRs appear to have less rework and greater general design awareness. He gave a series of nice tips in software development teams: — Store with the code, use plain text — Delegate ADR creation — Peer review as you would code — Foster a documentation habit — Make a decision, then document it — Not everything is an ADR! My own experience with ADRs is mostly in a higher level solution architecture context, but points to the same general principles: the threshold to documenting ADRs should be as low as possible, so try to store them in a tool or platform that your team is accessing on a daily basis already – and then coach them.

This was my fifth SATURN conference, and just like the previous years I returned home full of new ideas and inspiration, and with many useful new contacts. You can find recordings of all sessions on the SATURN YouTube playlist.I am already looking forward to the 2018 edition in Plano, TX.