Part 4: Visualizing your technical system's architecture

We have already covered the importance of talking to people to understand the current challenges and expectations, align with the organization’s goals, and gather or formulate a product vision.

Another critical step during your initial days as a software architect is to sketch the platform’s current state, highlighting its key characteristics, issues, and advantages.

Why?

Why should you create a diagram illustrating the system’s current state? Is the effort justified? Some people neglect to document the current state of their software, offering what I consider weak justifications. I will address some common arguments in this article and explain why they are flawed.

• The assumption that everyone in the organization knows about the system, although widely held, is often incorrect. While all technical staff might be familiar with the overall situation of the system, other members of the organization typically are not. Key stakeholders in the architectural evolution may not understand the necessity for technical modifications unless the current state and its challenges are depicted in a straightforward diagram and communicated effectively.

• “Code is documentation, and I added some comments to the repository that deploys our system. Check out these gorgeous Terraform scripts; they’re perfectly readable”. Some people are skilled at processing textual information. Geniuses might even interpret YAML, visualizing its indentation as animated colored blocks in their minds. However, this relies on prior knowledge and an extensive technical background acquired over the years. The impact of a visual representation cannot be compared to text-based explanations.

• It’s not worth the effort since these visuals will soon become obsolete. This argument holds some merit for component or class-level diagrams but is generally flawed for high-level system representations. Transforming a system at that level could take months or even years. Establishing a routine to review the documentation every three months, either through your documentation platform or independently, will do the trick. The insights provided by maintaining current visuals surpass the time invested quarterly to update them.

• The current state is rotten, so we prefer to document the target state directly. Analogous to planning a trip, knowing your starting point is essential to estimate the duration and determine the most suitable means of travel. Communication is key: while you know your current position, others might not. To effectively implement changes or undertake additional projects, people need to visualize the journey from point A to point B to grasp the planning fully. I will elaborate on this in an upcoming edition when I introduce planning tools.

Toolcard: Current System Overview

I introduced the Software Architect’s Toolbox as a streamlined framework to guide you through the standard architectural tasks. Let’s augment it with a new tool: the Current System Overview. All these tool cards are accessible in a Miro template: The Software Architect’s Toolbox in Miroverse.

You can begin this process from day one since you don’t need to rely on previously introduced tools, such as stakeholder feedback or the product vision. The current state doesn’t need their resulting artifacts.

I have some advice for you on accomplishing this task in the most efficient manner possible.

Co-create

When creating an overview of the current state, avoid assumptions. Seek assistance from others more knowledgeable about specific system parts and gather their feedback while crafting the diagram. Remember, being an architect doesn’t mean you work in isolation or are the most knowledgeable person; your role is to engage, communicate, and make others shine.

Storytelling

Recording a narration of your system’s high-level diagram is the best way to present it. This approach allows you to provide context about the system’s shape and the sequence of decisions that led to its current state. Discussions on how best to represent the current state (from the co-creation aspect described above) can refine this narrative.

Avoid complaining

There is no inherently “bad” or “good” system, and software development isn’t just about moving from a problematic state to “fix” it. Decisions were made within specific contexts and constraints; they cannot simply be labeled as “good” or “bad.” Perhaps they were appropriate at the time, for example, if the goal was to validate a business case.

Refrain from complaining or blaming others when describing the journey to the current state. Instead, focus on the positive aspects.

Use simple-enough tooling

You may be tempted to use advanced tools that allow for ‘coding’ the diagram and maintaining it in a git repository, with all the advantages that entails. I advise against this for several reasons:

• The quality of the results is often poor, particularly concerning connection lines, which can render the diagram confusing.

• It’s easy to become entrapped in technical details concerning the tooling and setup and ensuring it renders correctly for documentation purposes.

• Realistically, few people will contribute to this overarching diagram, and the most popular diagramming tools support collaborative features and version control regardless.

I typically use Miro for diagramming, but numerous other tools suit this task. At this zoom level, you must illustrate with boxes, arrows, and user/system icons.

Check out the MOSY framework page for more details about a simple but compelling approach you can choose to describe and model your system.

Merge and Clean up

If existing documentation on the current state is available, don’t ignore it. When feasible, use it as a source of inspiration. Consult the original authors for feedback on your proposed enhancements.

To prevent confusion, clean up any outdated diagrams, update all existing links, and clearly communicate the location of the new documentation.

Keep it simple and avoid technical details

The MoSy framework allows you to maintain a high abstraction level, which can serve as a common language across all areas of the organization.

Describe the actors, functions, and components in a style accessible to anyone, regardless of their role. The audience isn’t exclusively technical. Don’t use acronyms unless you provide a legend or context to explain their meanings.

Some examples

You can review the ready-to-use Miro template for documenting systems with MOSY, which includes an example visualization.

If you have any example diagrams you’d like to share with me and the community, that’s fantastic! Please post a picture in the comments or send me a message.

What’s next?

Once you’ve mapped out how your system currently looks, you can use what you learned from talking to stakeholders, the organization’s goals, and the product’s vision to start working on The Architecture Vision. This part results in another document filled with diagrams, but creating it isn’t as simple as just looking around and asking questions. You’ll need to work closely with other people to put it together. I’ll go into more detail about how to do this in the following blog posts.