How to think in terms of shapes, icons and legend

Conceptual diagrams are a visual way to show technical facts or how something works. These diagrams are created with rectangular boxes and connecting lines, where boxes are used to house concepts and lines are used to show the relationship between the two concepts.

In this article we will dig deeper into the visualisation of these concepts and relationships.

This article assumes that you have a basic understanding of conceptual diagrams from my previous article.

Using only rectangular boxes with connecting lines works perfectly fine in creating a meaningful diagram, but imagine what happens when we add a bit of context into the shape itself!

Rectangle vs the rest

In front-end environment, most topics can be expressed through:

• files and folders,
• what goes into each of these files and folders and
• their connections to one another.

See the example of the component tree below, where I’m planning to build a dynamic, configurable form using Vue.js.

Dotted boxes are clearly marked as .vue files. In the context of this example, the dotted line is used to indicate reusable components. Boxes can be of a solid, dotted or dashed border. As an author, you have to attach relevant meanings to these specially presented shapes.

Also, the diagram uses two colours: green and orange. Green boxes indicate known components, and orange ones are supposed to be rendered dynamically by <component :is=“…”>. The diagram is trying to show the possible values of :is=“…” prop that it can be either Checkbox, TextArea, InputText or Radio component.

You can see how concepts are often presented in rectangular shapes. But if we consider context and add a little bit of creativity, we will find other ways to illustrate ideas out of the box.

That is where we will take help from the flowchart notation symbols. We all have seen flowcharts and know what flowchart shapes look like. So, we are going to borrow some of the suitable shapes and bring them into a conceptual diagram.

For example, it’s possible to show when we want to refer to a single file versus multiple files. I have used multiple document shape👇 to indicate that Global and Layout middleware can affect more than one routes while Page middleware can be applied to one page at a time. Seeing the shape, our minds will immediately look for that additional meaning that there are three types of route middleware to begin with and how they differ from each other and their use-cases. (Concept reference: Nuxt-2 route middleware)

There are no restrictions to always find a unique shape for each concept. But we have some flowchart shapes, such as database, decision point and different types of arrows that fit perfectly well into our use-case.

Lines and arrows

Lines and arrows are the guiding lights of our diagram. They direct the user’s attention from one concept to the next, while showing how they are related to each other at the same time.

In this example above 👆 we have two folders: /global-components (pink) and /layouts (orange). The arrow's direction shows that the diagram flows from right-to-left. If we follow arrows with their connecting words, they form simple statements. E.g. Layout uses Base List Layout (component). Post imports Comment (component that is provided by the @vuepress/plugin-blog plugin) and so on. In Concept map literature, these simple statements are known as propositions.

Lines as well, can be solid, dotted or dashed. As an author, you should always assign relevant meanings to these specially presented lines using legend or annotations.

Annotations

Visual annotations allow us to add explanations or a comment that cannot be expressed with simple shape or in a less wordy way.

I remember Lucidchart was one of the first software that introduced sticky note shapes in their earliest version. I instantly fell in love with it! These days almost all diagramming software provides an option to add sticky notes.

Sticky note is my go-to shape for adding information that normally doesn’t fit into the diagram itself. Same goes for the speech bubble shape. I recommend using sticky notes and speech bubbles to add one of those important and ‘… thinking out loud’ thoughts into your diagram.

I have to credit Lucidchart here as well for introducing me to these large curly and square bracket shapes. Although they are annotation shapes, sometimes they serve as a way to group similar concepts in a diagram.

If these special shapes are not available in your choice of software, you can always fallback on our good old rectangle box as shown in the first example above.

Icons and legend

Icons are space efficient and say a lot without using any words. Icons are as essential to a good conceptual diagram as emojis are to any chatting app these days.

Legend is a small section with a list of words or phrases explaining the icons or special characters used in the diagram.

Icons and legends go hand-in-hand. They act as a space saving mechanism that can help us add more meaning to our diagram. Every time we use an icon to show something, it becomes necessary to explain it in the legend section. It’s good practice to write the legend content in short words or shorter phrases, rather than longer statements.

Let’s see how we can think in terms of the legend.

Consider this example of Nuxt-2 Context which presents a perfect use-case for adding a legend section. Nuxt Context provides all of these keys that we see in the diagram. They are a combination of functions, objects, boolean values, some only available on either client or server and sometimes both and more! Now imagine if we were to write these key attributes in words! It would clutter the diagram instantly and make it really hard to read.

Earlier we saw how we can use bracket shape to group similar concepts, here’s another example of how we can use colours to do the same. See how route related keys are grouped together in dark-green circles.

With legend on a side and colour-coded circles, we are able to save space while keeping the key focus intact. E.g. see the env key in the pink circle. We can easily tell that env key is 1) an object that’s 2) provided by Webpack during build and 3) it’s available on both client & server.

Now this is an extreme example of a legend. But generally, when I find myself repeating something more than twice in a diagram, I put it under a legend section.

Formats

Final delivery format of your diagram is something you should start thinking about from the beginning. That way there are less edits and rearrangements to make as an afterthought. I create most of my diagrams for printing and blogs.

For printing, A4 size document works perfect as it is easy to print and big enough to pack a lot of information.

For blog posts, social media and general web, any accessible image format is suitable. If your diagramming software allows exporting PDFs, then PDF format provides high-resolution, tiny file-size as well as accessible hyperlinks within the document to add further reference links along with the diagram.

Wrap up

If you have made it this far, thank you so much for reading my article on this topic! ❤

So to sum it up, we have shapes, lines, arrows, annotations and colour codes to create our diagram. We may not have to annotate and colour code shapes every single time, but rather use them only when they make sense and help simplify complex topics.

Much of what we have learned here will depend on the diagramming software of your choice, but understanding these visual elements will help you:

• Add bit of a visual context,
• Think in terms of visual composition of a diagram and
• Reinforce the overall meaning of the key topic.

I hope this article has inspired you and given you easy starting points to start thinking about your diagram project.

Next, I am planning new contents around tooling and software to create diagrams. So, follow me at @krutiepatel to get notified of upcoming contents.

Resources

Article: Building an Interactive and Distraction-Free Form with Vue. You will also find other related diagrams in this article for your reference.

Example diagrams mentioned in this article:

• Nuxt lifecycle hooks
• Building VuePress blog theme
• Nuxt Context