Using Diagrams to Improve Technical Communication

“You know what architecture really is? It is an art of drawing lines. With an interesting rule that once you have drawn a line all the dependencies that cross that line point in the same direction.” –Robert C. Martin

Picture this: you're the most experienced software engineer in a small startup, and you've just been tasked with designing a complex system that will be the backbone of your company's operations.

You're excited to dive in and start coding, but then it hits you—how will you ensure that your team understands the intricacies of the design? How will you communicate the system's architecture to stakeholders who may not have a technical background?

This is where diagrams come into play — they are powerful tools that can convey complex information concisely. They allow you to document systems, share knowledge, and deepen your own understanding of your designs.

Many engineers often skip upfront design and jump straight into coding, especially with the adoption of agile and lean startup methodologies. While there may be limited time for extensive upfront planning, some level of design is still essential.

For example, imagine you want to design a circuit breaker component.

A circuit breaker is a design pattern that can be used to increase the robustness of your system and protect it from failures of other components (or third-party systems). It enables your code to verify external component availability before executing actions.

To build a circuit breaker, you need to approach the problem with a clear understanding of the system's requirements. You can begin with a draft of the main interface below:

interface CircuitBreakerInterface {
  isAvailable(serviceName: string): boolean;
  reportFailure(serviceName: string): void;
  reportSuccess(serviceName: string): void;
}

To take it a step further, you can draft some code to test the interface and ensure it's functional.

This could be a unit test or just a draft of code that doesn’t have to compile. At this stage, just make sure that the interface you create is clear and easy to use:

let userProfile = null

if (circuitBreaker.isAvailable('UserProfileService')) {
  try {
    userProfile = await userProfileService.loadProfile()
    circuitBreaker.reportSuccess('UserProfileService')
  } catch (error) {
    if (error instanceof UserProfileServiceException) {
      circuitBreaker.reportFailure('UserProfileService')
    } else {
      // Service is available, but another error occurred
      log.error('Error occurred while loading user profile:', error)
    }
  }
}

if (userProfile === null) {
  // Handle the error gracefully
  showMaintenanceMessage()
}

Once you have a solid understanding of the main use cases, you can leverage sequence diagrams to illustrate the interaction between clients and the circuit breaker:

The diagrams provide different perspectives of the design, which helps you better visualize it. This, in turn, reduces the risk of creating an unrealistic design and investing significant time and effort into it before having a chance to validate it.

📝 Tip: If you find it challenging to draw diagrams initially, start by documenting your existing work. It's easier to create diagrams for applications and features you've already built and fully understand.

If you are a frontend engineer, diagramming skills can also be very helpful when designing client-side applications that prioritize performance and user experience.

By visualizing your thought process in diagrams, you can effectively explain concepts like component architecture or front-end architecture in general.

Three types of diagrams are particularly useful for documenting and understanding large-scale systems: Use Case, Class, and Module diagrams (similar to Class Diagrams, but focus on the higher level of abstraction).

As your company scales up and your teams grow larger, these diagrams become increasingly beneficial.

While there are established rules and notations for creating diagrams, I think the most important thing is to focus on making your diagrams understandable.

Think of your diagrams as a conversation starter, not the end product. Use them as a tool to facilitate discussions, gather feedback, and continuously refine your designs.

The more you practice creating diagrams, the better you'll become at distilling complex systems into visual representations that everyone can understand.