A Comprehensive Guide to Technical Diagrams

In a previous article, I explained the importance of technical documentation for your team. In this article, I will cover the following:

• Identifying the type of documentation your audience expects from you
• The beneficial role of visualization in understanding concepts
• The commonly used technical diagrams and models

Identify the type of documentation your team needs

Every product or service works with data. This data could be created from scratch, sourced from various systems, or a mix of both. Ideally, you should thoroughly understand this data’s structure and how it flows from a business perspective.

A practical approach is creating a conceptual model that provides a clear idea of the subject. This type of model should help everyone gain a better understanding of the topic it represents.

With a model like this, you can always view the bigger picture of all your components and how they relate to one another. However, these models can sometimes be challenging to read and comprehend, particularly if the system is complex, as shown in the example below:

Just one part of a huge conceptual diagram of our processing platform

Creating a high-quality technical diagram is beneficial, but it’s pointless if only you can understand it. That’s why it’s crucial to discuss with your colleagues and stakeholders what kind of documentation you need to create. Perhaps your organization already has guidelines or even templates (like ours) for technical documentation, or you could learn from other teams who have already created their documentation. If not, you can start from scratch and later identify reusable patterns and common blocks, which will help you design your own templates.

We aim to develop templates for all frequently used documentation. This approach helps our various teams better structure our documentation without having to give it too much thought. I’ll share these templates later, in the sections for internal and external documentation.

Why сombining visuals and text matters

Everyone knows that pictures are often easier to understand than a massive block of text. Presenting information visually can help others grasp the concept better than if they had to read through pages of text. Still, it’s essential to remember that text is needed to explain the finer details.

Let’s consider the following sequence diagram as an example:

What can you gather from this diagram? You can identify who is involved in the process, the type of interactions occurring, and when the process starts and ends. But it doesn’t cover all the necessary details, such as:

• How do we label an email as unsent?
• How do we compose a new email?
• Where do we store the downloaded email?

To address these questions, you could make more diagrams, but keeping them all updated can be challenging. The method we prefer is to add details using text. This way, you have both a visual guide and thorough information, making it easier to keep everything up to date.

The technical diagrams and models we use

Use Case Diagram

We typically use this kind of diagram when we want to show basic requirements through a user’s interactions with a system. It’s the first step in more detailed investigations, and it helps clarify user needs and roles. This diagram answers questions like who is involved and what they will do.

Process model

A sequence diagram is useful for technical illustrations, but it might not be the best choice for sharing with product managers, business analysts, and other non-technical team members.

A process model provides a broader overview of a process, showing the interactions among different systems, teams, and players, while offering a more business-oriented perspective. This means the same process could be visualized in two ways:

• Sequence Diagram — to discuss with technical team members, either from your team or external teams
• Process Model — to depict the same process for colleagues from business departments, with minimal or even no technical details

There are a few different ways to implement process modeling:

• Activity Diagram (UML — Unified Modeling Language)
• BPMN (Business Process Model and Notation)

These two methods share many similarities and can often be used interchangeably. I lean towards BPMN because we deal with many event-driven processes, and it’s simpler to design these using BPMN’s standard components, as shown below.

BPMN

Just a simple example of how BPMN helps you to show the type of interaction and type of actions that are involved in a process.

Flowchart

To represent the execution of some logic, you’ll need to create a flowchart. It offers a comprehensive view of your entire process at every step, highlighting why and where it could go in one direction or another.

We use these diagrams when we want to visualize a small part of a logic flow, an algorithm, or a procedure (like an API method). To enhance these diagrams, we include hyperlinks to detailed descriptions of each process.

Here’s a small example of a flowchart that I made when we introduced a new payment flow for our client, focusing on a specific attribute of a method from our database:

Sequence diagram

To be honest, before my time at Exness, my experience with sequence diagrams was only theoretical. But after creating a few, I now see them as indispensable for process-related technical documentation.

A sequence diagram provides everything you need to know and demonstrates a process from the perspective of the service. This includes:

• The list of services involved in each phase
• The type of interaction (synchronous/asynchronous) for each function or service call
• The duration of service activity
• Basic, alternative, and exceptional paths

We use this type of diagram to describe nearly every process (usually involving at least three services), new service integrations, and modifications to existing implementations (like shifting from synchronous to asynchronous integration).

PlantUML

There are numerous tools and editors available to help you create vibrant sequence diagrams with a variety of colors and symbols. However, one of the simplest ways to create and maintain sequence diagrams is by using PlantUml. This tool saves you the hassle of manually moving elements, changing enumeration, etc. You can find all the details on it here: https://plantuml.com/sequence-diagram.

Data modeling

Our primary tool for data modeling is an ER (entity-relationship) diagram, which is widely used for designing relational databases. When creating a new database, it is important to have a good understanding of the subject area or domain. With this knowledge, you can identify the key elements for your ER model:

• Entity: represents an object or a component within your domain that plays a role in processes.
• Attributes: refers to the properties or characteristics of an entity.
• Relationship: determines how entities interact and relate to each other, such as a “parent-child” relationship.

ER diagrams can be categorized into three levels of abstraction:

• The conceptual model, as I mentioned earlier, offers benefits but can be challenging to understand and maintain.
• Logical model: at this level, the ER diagram provides additional details about data elements and their relationships.
• Physical model (represents the actual architecture of your database, including its data structures and relationships).

The key difference between the two last models is that the logical model does not depend on your Database, whereas the physical one is the elimination of your concrete database’s schema.

We utilize both logical and physical models:

• When we’re working with a new domain or a service we
• Create a logical model
• Apply all constraints/restrictions on it
• Create a physical model
• In the case of existing services with a database, we focus on creating a physical model to enhance our understanding of the database structure.

The importance of the database model for stable operations cannot be overstated. It is crucial to invest sufficient time in the modeling stage to explore various implementations and find the most suitable one for your requirements.

Now, let’s summarize the pros and cons of the different diagrams and models and determine when it is best to use them.

Conclusion

There are various ways to create technical documentation, depending on the complexity of your processes, scope, and what you want to describe. Some documents and diagrams, such as flowcharts, are universal, while others like sequence diagrams are more technical-focused. Feel free to explore other options like C4 or state diagrams which I didn’t mention in the article. Don’t hesitate to try different approaches.