Designing Communication, Communicating Design

We work in a communications industry.

We create and maintain systems to move information around in order to get things done. That information moves between people and systems in combinations and configurations too numerous to count. In spite of that, we don’t do that great a job of communicating what should be, for us, extremely important information. We tend to be really bad at communicating the architecture of our systems – structure, behavior, and most importantly, the reasons for the decisions made. It’s bad enough when we fail to adequately communicate that information to others, it’s really bad when we fail to communicate it to ourselves. I know I’ve let myself down more than once (“What was I thinking here?!”).

Over the past few days, I’ve been privileged to follow (and even contribute a bit to) a set of conversations on Twitter. Grady Booch, Ivar Jacobson, Ruth Malan, Simon Brown, and others have been discussing the need for architectural awareness and the state of communicating architecture.

This exchange between Simon, Chris Carroll and Eoin Woods sums it up well:

@KuhlWaterloo @ivarjacobson @Grady_Booch I've run architecture katas for 10K+ people and they do struggle to communicate architecture 😞

—
Simon Brown (@simonbrown) October 23, 2016

@simonbrown @KuhlWaterloo @ivarjacobson @Grady_Booch For want of a language or for want of understanding what needs to be communicated?

—
Chris F Carroll (@chrisfcarroll) October 23, 2016

@chrisfcarroll @simonbrown @KuhlWaterloo @ivarjacobson @Grady_Booch both in my experience

—
Eoin Woods (@eoinwoodz) October 24, 2016

First and foremost, an understanding of what the role of a software architect is and why it’s important is needed. Any organization where the role is seen as either just a senior developer or (heaven help us!) some sort of Taylorist “thinker” who designs everything for the “worker bee” coders to implement, is almost guaranteed to be challenged in terms of application architecture. Resting on that foundation of shifting sand, the organization’s enterprise IT architecture (EITA) is likewise almost guaranteed to be challenged barring a remarkable series of “happy accidents”. The role (not necessarily position) of software architect is required, because software architecture is a distinct set of concerns that can either be addressed intentionally or left to emerge haphazardly out of the construction of the system.

Before we can communicate the architecture of a system, it’s necessary to understand what that is. In “Software Architecture: Central Concerns, Key Decisions”, Ruth Malan and Dana Bredemeyer defined it as high impact, systemic decisions involving (at a minimum):

• system priority setting
• system decomposition and composition
• system properties, especially cross-cutting concerns
• system fit to context
• system integrity

I don’t think it’s possible to over-emphasize the use of “system” and “systemic” in the preceding paragraphs. That being said, it’s important to understand that architectural concerns do not exist in a void. There is a cyclic relationship between the architectural concerns of a system and the system’s code. The architectural concerns guide the implementation, while the implementation defines the current state of the architecture and constrains the evolution of future state of the architecture. Code is a necessary, but insufficient source of architectural knowledge – it’s not enough. As Ruth Malan noted in the Visual Design portion (part II) of her presentation at the Software Architect Conference in London a year ago:

While the code serves as a foundation of the system, it’s also important to realize that the system exists within a larger context. There is a fractal set of systems within systems within ecosystems. Ruth illustrated this in the Intention and Reflection portion (part III) of the presentation reference above:

[Note: Take the time to view the entirety of the Intention and Reflection presentation. It’s an excellent overview of how to design the architecture of a system.]

The fractal nature of systems within systems within ecosystems is illustrated by the image at the top of the post (h/t to Ric Phillips for the reblog of it). Richard Sage‘s humorous (though only partly, I’m sure) suggestion of it as a meta-model goes a long way towards portraying the problem of a language to communicate architecture.

Not only are we dealing with a nested set of “things”, but the understanding of those things differ according to the stakeholder. For example, while the business owner might see a “web site” as one monolithic thing, the architect might see an application made up of code components depending on other applications and services running on a collection of servers. Maintaining a coherent, normalized object model of the system yet being able to present it in multiple ways (some of which might be difficult to relate) is not a trivial exercise.

Lower-level aspects of design lend themselves to automated solutions, which can increase reliability of the model by avoiding “documentation rot”. An interesting (in my opinion) aspect that can also be automated is the evolution of code over time. What can’t be parsed from the code, however, is intention and reasoning.

Another barrier to communication is the need to be both expressive and flexible (also well illustrated by Richard’s meta-model) while also being simple enough to use. UML works well on the former, but (rightly or wrongly) is perceived to fail on the latter. Simon Brown’s C4 model aims to achieve a better balance in that aspect.

At present, I don’t think we have one tool that does it all. I suspect that even with a suite of tools, that narrative documents will still be way some aspects are captured and communicated. Having a centralized store for the non-code bits (with a way to relate them back to the code) would be a great thing.

All in all, it is encouraging to see people talking about the need for architectural design and the need to communicate the aspects of that design.

Advertisement

“Architecture as Narrative” on Iasa Global Blog

Architectural design as a form of storytelling is an established theme.

See the full post on the Iasa Global Blog (a re-post, originally written for the old Iasa blog).

The Never-Ending Narrative of Architecture

All of my creation is an effort to weave a web of connection with the world: I am always weaving it because it was once broken.

Anaïs Nin by way of @RuffyanMe

When is an architect’s job done? Is it upon completion of the “design phase”? Is it when the project is complete?

In my opinion, the best definition of the architectural process (see slide 16) is Tom Gilb’s: “A continuous, and lifecycle long, activity of finding means for ends”. The activities facilitated by the application are unlikely to be static, so it is unrealistic to expect it to remain the same. Even where the business doesn’t change significantly, our understanding of it may:

I bet the users are very grateful at first, but then they come to rely on it. And, what’s more, they like the system less and less over the course of time. Every time the USPS changes the price of postage you have to go into this system and made changes, and, what’s worse is that the part that generates the documents seems to break every time there’s a new version or even an update to Word.

Erik Dietrick, “Beware Mindless Automation”

Even if a particular business process was unchanging and its automation was executed perfectly, the platform on which it runs will not. Failure to plan for platform evolution is planning to fail due to lack of maintenance.

In short, an application is a relationship. Unless you plan to never see its users again, it’s a long-term commitment, not just a project. So long as the application exists, there is a need for the architect role to provide advice on the evolution of the product and its platform. Without this continuity of vision, the result is likely to be the “Shantytown” pattern described by Foote and Yoder in “Big Ball of Mud”:

All too many of our software systems are, architecturally, little more than shantytowns. Investment in tools and infrastructure is too often inadequate. Tools are usually primitive, and infrastructure such as libraries and frameworks, is undercapitalized. Individual portions of the system grow unchecked, and the lack of infrastructure and architecture allows problems in one part of the system to erode and pollute adjacent portions.

If the architectural process can be described a narrative, it should also be seen as a story consisting of several component stories, carrying the product from cradle to grave(*). Maximizing cohesion within a given narrative (release) is important. Likewise, benefits will accrue from maintaining continuity from one narrative to the next.

The connection between the application and the ends it serves is seldom static. The longer the web is left unattended, the more likely it is to break. Much can slip through a broken web, and each escape widens the breach.

Maintenance can seem costly without the perspective of the cost of replacement, not to mention value lost to obsolescence.

* It’s not exactly “never-ending”, but I like alliteration, so the title stands. 😉

Architecture as Narrative

(Mirrored from the Iasa Blog)

Architectural design as a form of storytelling is an established theme. Ruth Malan’s January “A Trace in the Sand” highlighted a quote from “The 22 rules of storytelling, according to Pixar” that reinforces the analogy:

#11: Putting it on paper lets you start fixing it. If it stays in your head, a perfect idea, you’ll never share it with anyone.

Getting a design out into the light of day where it can be polished via collaboration and critique is something I definitely value. I decided to see which other Pixar rules spoke to me as well.

#2: You gotta keep in mind what’s interesting to you as an audience, not what’s fun to do as a writer. They can be v. different.

If the technology is driving the architecture rather than the stakeholders’ needs, you have a problem.

#3: Trying for theme is important, but you won’t see what the story is actually about til you’re at the end of it. Now rewrite.

You can shape your solution to the problem, or you can try to impose your solution on the problem. The problem will most likely be fluid, so how robust will a rigid solution be?

#5: Simplify. Focus. Combine characters. Hop over detours. You’ll feel like you’re losing valuable stuff but it sets you free.

Good design is as much about editing as it is about composition. There will be plenty of complexity inherent in the domain, so you don’t need to add your own.

#7: Come up with your ending before you figure out your middle. Seriously. Endings are hard, get yours working up front.

It’s tempting to start solving the problem right away, but that can lead to dead ends. You have to know where you want to go before you pick your route to get there. Just remember that today’s ending will be tomorrow’s beginning.

#8: Finish your story, let go even if it’s not perfect. In an ideal world you have both, but move on. Do better next time.

Your purpose is to deliver value, which can’t happen until there’s an actual delivery. Perfection that never sees the light of day is worthless, and today’s perfection is tomorrow’s “not quite”.

#22: What’s the essence of your story? Most economical telling of it? If you know that, you can build out from there.

Simplicity and focus (#5) is important enough to repeat.

The narrative of an architecture should be an epic, moving from birth to maturity and ultimately to closure. Like Scheherazade, it’s important that our stories do not end too soon. Keeping the principles above in mind can help.