How to Create Diagrams for Technical Blog Posts

Published on Sep 13, 2024 in processes by Kirstin Spivey
5 minute read

Writing technical articles is a complex process consisting of different components. You have to research the topic, create demo applications, troubleshoot any issues, and then write the actual article.

For some articles, it’s also helpful to include an architectural diagram, which can help readers better understand system structure, data flow, or interactions between different systems or services.

In this article, we’ll define what an architecture diagram is, explore different tools you can use to create them, and provide a few tips to help you get started.

What Are Architecture Diagrams?

An architectural diagram is a visual tool that shows how different parts of a system or application work together. It acts like a blueprint, mapping out connections between components like databases, servers, APIs, and user interfaces.

For example, this article uses a diagram in the very beginning to visualize what’s going to be created:

While it would be possible to communicate the complexity of this architecture with words, the diagram communicates more clearly and efficiently.

Architectural diagrams can also highlight dependencies, data flows, and the overall organization, making it easier to identify potential issues.

What Makes an Architectural Diagram Good

A good architectural diagram effectively communicates the design and structure of a system and typically focuses on the following:

• Clarity and simplicity: Use clear, straightforward symbols and labels to represent components. Additionally, make sure you use descriptive labels and annotations to clarify the function and purpose of each component.
• Consistent layout: Arrange elements logically, with a consistent style and structure to make the diagram easy to follow.
• Key components: Highlight all crucial elements, including their relationships and interactions.

These elements ensure that the diagram is both informative and accessible, helping readers easily visualize complex concepts.

Tools for Creating Architecture Diagrams

Now that you know more about the different components that make up a good architectural diagram, let’s take a look at some tools you can use to create one.

Google Drawings

Like most things in the Google ecosystem, Google Drawings is easy to get started with. While it may not offer advanced features, its straightforward interface allows you to create basic, effective diagrams.

Google Drawings works in every browser, but if you’re using a Chromium-based browser like Chrome or Edge, you can type drawing.new directly into the address bar to open a new drawing.

ExcaliDraw

Sometimes you want something a bit different that resembles a quick sketch. This is where you may want to try out ExcaliDraw. It lets you create illustrations that looks like what you’d draw on a whiteboard.

Whether you use Google Drawings or ExcaliDraw mainly comes down to preference.

Draw.io

Draw.io is a free and easy-to-use tool that offers a more extensive set of features than Google Drawings and is designed specifically for diagramming.

It integrates well with cloud storage services like Google Drive and Dropbox and supports real-time collaboration.

Inkscape

If you’re interested in making more complex diagrams, Inkscape offers precise control over vector graphics, enabling detailed and accurate illustrations. It supports a wide range of file formats and includes advanced features like layers, object grouping, and path manipulation.

It’s also free, open source, and available on Windows, Linux and Mac

Tips for Creating Diagrams

Now that you’re ready to create some visually appealing, well-structured architectural diagrams, the following tips can help you get started.

Practice Makes Perfect

As with most things, creating architectural diagrams takes practice. On the surface, it may seem like architectural diagram creation is a matter of knowing all the prerequisites, but in reality, it’s still something that takes skill. If you haven’t created diagrams before, don’t get frustrated when your first couple don’t look that great. Keep trying and you’ll be creating beautiful diagrams in no time.

Keep the following in mind if you’re just starting out:

• Use consistent colors and fonts: Stick to a limited color palette and uniform fonts for a professional look. Also, make sure your color choices enhance readability. Have you selected high-contrasting colors for your background and font?
• Keep it simple: Avoid clutter by focusing on key elements and removing unnecessary details.
• Utilize white space: Give elements room to breathe to prevent the diagram from feeling crowded. Along with that, don’t try to cram everything into the diagram, the content that goes along with the diagram can help fill in the gaps.
• Align elements (when possible): Ensure that shapes and lines are neatly aligned for a clean, organized appearance. Don’t forget to think about the position of elements and texts. Make sure that the text accompanying an element is close to it, and is not ambiguously placed.
• Use shapes: Standard shapes and symbols such as arrows and squares can help provide clarity.
• Use visual hierarchy: Highlight important components with size, color, or placement to guide the viewer’s attention.
• Maintain proportions: Keep element sizes proportional to their importance or relationship to avoid misleading representations.

Think about the Reader

Of all the tips in this article, this is probably the most important one: Don’t forget who you’re creating your diagram for. Is it a beginner? Make sure you’re content is as simple as possible. Does your reader have years of experience? Then using more complex terminology/visuals is probably okay.

It’s easy to get caught up in your diagram and forget critical information. Take a step back (maybe even a few hours or days away) and come back and review your content through the eyes of your reader. Sometimes a little break and a reminder of who your audience is, is all you need to take your diagram from good to great.

Conclusion

Making an architecture diagram isn’t the most difficult task, but it does require practice and some thoughtful planning. A poorly designed diagram can confuse readers instead of clarifying your points. To avoid this, always consider how your diagram aligns with the content your presenting. Thoughtful design can turn a good architectural diagram into a great one.

Build a Blog that Software Developers Will Read

The Technical Content Manager’s Playbook is a collection of resources you can use to manage a high-quality, technical blog:

• A template for creating content briefs
• An Airtable publishing calendar
• A technical blogging style guide

Download Now!