How to Create Diagrams for Technical Blog Posts

Published on Jan 04, 2022 in processes by Kasper Siig
4 minute read

Writing a technical article consists of many different components. You have to research the topics you are writing about, at times create demo applications, and of course, you have to write the article. For some articles, you also have to create architecture diagrams. While not a necessity, an exemplary architecture diagram can help your readers understand the points of your article a lot better.

Whether it be a diagram of how the different parts of an application work together or an example of how an application flows, you can typically get a lot across with a suitable diagram, compared to typing everything out. In this article, we’ll cover a bit more about what an architecture diagram is, tools for creating them, and a few tips to help you on your way.

What are Architecture Diagrams?

As stated in the introduction, architecture diagrams are a way to help your readers understand the points of your article. Many technical articles are tutorials, such as a quick step-by-step instruction list on how to get something running. An example of this could be a CRUD API built with PostgreSQL, NodeJS, and OpenFaas.

That’s a very specific example because it’s taken from this article. This article has an excellent diagram in the very beginning showing what is going to be created. You can see it here:

Writing all the information for what this application includes would be possible. But, you will have to be very specific to get the point across in your writing, as well as when you build the architecture diagram. A good architecture diagram includes the most particular points needed to understand the application flow and arrows to guide the reader through the diagram. You don’t need much more to make a proper diagram.

Tools for Creating Architecture Diagrams

Now that you know what it means to create an architecture diagram, you also need to know how you can make it. Luckily there are plenty of tools out there to help you with this. Here are just a few.

Google Drawings

Google Draw is a straightforward tool to use. It’s easy and not very complex. This does mean that the diagrams you can create with this tool aren’t going to be too advanced, but that’s not to say that you should steer away from it. The times you will have to create diagrams beyond what Google Drawings is capable of will be very few.

If you are using a Chromium-based browser like Chrome or Edge, you can type drawing.new directly into the address bar, and you’ll be opening a new drawing. This way, you can quickly try out what Google Drawings is capable of.

ExcaliDraw

Sometimes you want something a bit different, something more resembling a quick sketch. This is where you may want to try out ExcaliDraw. ExcaliDraw allows you to create illustrations like what you draw on a whiteboard. Whether you use Google Drawings or ExcaliDraw mainly comes down to preference.

To try it out, visit https://excalidraw.com/.

Tips for Creating Diagrams?

Now you know more about creating an architecture diagram and how you can do so. Here are a few tips to think about when you make diagrams.

Practice makes Perfect

Like with anything, making architecture diagrams takes practice. On the surface, it may seem like making diagrams 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 worry when they don’t come out great. Keep going at it, and you’ll be creating beautiful diagrams in no time.

Think About the Reader

Something familiar between articles and diagrams is that you have to take a step back and consider whether what you’ve created makes sense for new readers. Sometimes you can get too caught up in it and not realize that the diagram is missing some critical information that you may know but that the reader may be missing.

Think about colors

Something that can often be missed when creating an architecture diagram are the colors. Try making components of the same variety the same colors, making it more evident to the reader. If you have a diagram consisting of virtual machines and storage blocks, you could, for example, make the VMs blue and the storage blocks green.

Conclusion

Making an architecture diagram isn’t the most challenging skill in the world, but you do have to give it some thought. A bad diagram can risk getting the reader more confused rather than being helpful. Make sure to think about your diagrams in relation to the content you are writing.

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!