My latest article published in InfoQ discusses the difficulties of not only finding, but also modelling and evaluating architectural dependencies.
You can read the article here.
Why do we have balls of mud?
IT complexity is often described using metaphors such as “the big ball of mud” or the “software hairball syndrome” to illustrate a haphazardly structured software system. What intrigues me about these systems is their stubborn ability to morph into existence and their persistence. Almost all the companies that I’ve worked with over the years have at least one of these systems and many are several systems intertwined. And they are clearly problematic to maintain and change.
While searching for answers, four approaches repeatedly turned up in different disguises:
- Delegate – typically to the Enterprise Architecture team, so when it doesn’t work, we can blame them (win either way).
- Let’s move it to the cloud – it is same shape, so it should fit (Mud as a Service?).
- New tool – where is that mud removing feature?
- New method – the IT department is incompetent, so they’ll need a bit of extra help.
Leaving the tongue-in-cheek behind, all the approaches seemed to me like going on a diet. Sure, if there is a lot of complexity then we need to remove it. But diets are rarely much fun, which makes it hard to motivate people and easy to stop regardless of achievements. In fact they often make the problem worse, because they don’t stop you from regaining weight. Diets also don’t address the reason behind the excess weight – we need to look at our habits to find (one of) the reasons.
People don’t create complexity on purpose or out of incompetence. Complexity is rarely in people’s own interest. And if we were incompetent then large corporations shouldn’t be able to function; let alone reasonably well. So why do we end up with complexity despite our best efforts?
While I cannot claim to have the answer, I do think the problem is closely related to how an organisation makes design decisions.
Decision Context
Conway observed that the organisation’s communication structure is mirrored in its software systems. That is the organisation’s accumulative set of design decisions agreed through the organisation’s communication structure is what forms the systems. Software architecture is about guiding and constraining design decisions, which architects facilitate through the available communication structures.
But there is obviously more to it than just structure – what (the decision) we communicate are also important.
Tyree and Akerman’s article, “Architecture Decisions: Demystifying Architecture” (PDF) describes the elements (“what”) of an architectural decision well. Their definition stress the importance of capturing the decision context such as the associated requirements, constraints, related decisions, and rationale (labelled “context D” in below diagram); as well as the consequences (also referred to as implications). We tend to think of consequences as something relative localised, but architectural decisions often have a much wider impact in four different dimensions: project, system, domain, and enterprise. The same decision will have different consequences depending on its context (“C”):
- the project; the context for making and implementing decisions
- the system; that is the changed system or impacted another system change
- the domain; a horizontal aspect such as security, operations, or a single, enterprise wide business function
- the enterprise; the synergy of all domains
The third part is decision priority. Some decisions cannot be made before others, while others are closely interlinked. We structure decisions into decision dependency trees (explicitly or implicitly). In a pure architect only world, we’ll expand and prune the decision tree, as we work our way through it while carefully evaluating the available options. In reality, there are many influences on the decision priority including schedule, cost, available information and the organisation itself (labelled as context P).
The above diagram seeks to illustrate the three parts: Priority, Decision, and Consequence with their respective contexts. For smaller teams, context C, D, and P are just “the context”, but this is rarely the case within larger organisations. What is the result of this less than perfect context overlap (between P, D, and C)?
Context Misalignment Creates Complexity
Most architects have experienced the scenario, where project schedule drives the decision priorities. This forces the need to take shortcuts through the decision tree, and we risk making less than ideal decisions, either because we don’t have time to find the required information or have insufficient time to perform proper analysis. Another key factor is the organisational structure itself. Bass and others found that projects run into problems, when the chosen architecture required subsequent communication needs which the organisation structure couldn’t support – the anti-pattern of Conway’s Law if you like. What’s interesting about Bass’ findings is that we give priority to decisions that we can solve with a given organisational structure. We do this rather than focus on changing the organisational structure to support the actual, required decision structure.
Making decisions without consideration for their multi-dimensional impacts will also cause problems. While we tend to blame the project manager for forcing us to consider the schedule, cost and available resources, architectural decisions made without appropriate consideration for all four dimensions also adds to the complexity – for example:
- A functional focus without a view to operational domain (project vs domain) will add to the system support and maintenance cost
- Accepting system capabilities without questioning the functionality integrity (system vs domain) will compromise domain level capabilities
- Driving a strong domain strategy risks compromising core systems and the enterprise itself (domain vs systems vs enterprise), and;
- Ivory tower syndrome (enterprise vs the rest)
While IT complexity might be one of those impossible problems to solve, I believe that it goes along way to simply acknowledge and attempt manage the decision context.
The Elusive Knowledge
“If only they had written a better design document” complained the (to remain unknown) architect in frustration after a series of “he said”, “she said”, and “no, that’s not what I meant”. Software development is tricky business and more so the larger the system. Large systems mean more people with smaller pieces of responsibilities (relative to the whole) necessitating more communication to ensure a cohesive system. And our faulty memory makes it wise to document the design.
But what stops us from writing better documentation? What do we mean by “better”?
Architects write documentation to communicate what we know about the software. Software is difficult to observe, see or feel unlike the way we can with buildings. Yes, we can see its user interface, but that’s like attempting to assess the shape, size, location, direction and speed of an iceberg based on an aerial photo. Software architecture is, at its core, a knowledge management problem.
Knowledge is the awareness, understanding and experience with the collected information, where information convey data and their relationships (Zins, 2007). Within a project context, either three (knowledge, information and data) is: documented or undocumented; and implicit or explicit – as illustrated in figure 1 and described by Kruchten, Lago, and Vliet (2006).
Figure 1 – The Relationship Matrix of Knowledge
The implicit, undocumented knowledge includes what we don’t know what we don’t know. But it also includes people’s experience or intuition (gut feel), as well as the “of course” knowledge. We use checklists and methodologies to cover us against what we don’t know, we hire good people to gain the best experience, however, the “of course” knowledge is difficult to quantify, as we might be unaware. “Of course” is a risk to the project; what is obvious to you is not obvious to the team. If projects are large enough, then people will also build up a certain amount implicit knowledge about the project, its deliverables, and involved teams and systems.
The implicit, but documented knowledge is the unattainable – either because we lost or cannot find the manual, incomprehensible (source code), or inaccessible due to contractual or intellectual property limitations. Old systems or third-party developed software will contribute to this category.
The explicit, yet undocumented knowledge cover our observations, the water cooler discussions, and general awareness which we can articulate. This knowledge will quickly become implicit knowledge if it is not documented. And similar to the implicit knowledge, people working as part of large projects will build up this type of knowledge about the project and associated systems.
The last category is what we deliver – explicit, documented knowledge about the new system. However, the problem is to get all of the relevant knowledge into this category.
Can we do that? No.
Nonaka (1991) identified four knowledge creating processes in his seminal HBR article “The Knowledge-Creating Company”. Rather than just walk you through the four processes, figure 2 attempts to illustrate them.
Figure 2: The Knowledge Creation Process
The first part involves observations to gather tacit data. If we observe data (aka analyse) then we may find information. This we may be able to articulate into explicit information, which we can then organise into documents with text, charts and diagrams. We can then take the explicit information and apply it within a context to solve a problem or support a decision (the tacit knowledge). And observations about tacit knowledge form a critical part of architectural evaluations such as ATAM.
The problem is that these knowledge creating processes (illustrated as arrows) don’t retain information or knowledge perfectly – some gets left behind. And each of them creates new implicit knowledge – typically in the form of experience – which can be difficult to capture accurately. Knowledge is elusive by nature and therefore challenging to capture perfectly.
To create better documentation, we need to “deliver” all three types of sharable knowledge:
- Tacit/implicit – that is mostly in people’s heads. We may be able to express it and thereby make it explicit; or we may not. The portion we can articulate, we deliver through presentations, workshops and other forms of meetings.
- Documented – it exists in a written form (email, notes, whiteboard, or word processing document). While these are important during data gathering and analysis to create information, we need to create a formal home either as an appendix or separate support documentation.
- Formal refers to not only the documented form, but also that it is structured in some systematic way using a modelling language (e.g. UML, ArchiMate, SysML, etc.).
Better architectural documentation must address all three types of knowledge, their role in the creation process, and their relationships.
