How to create technical conceptual diagrams

Beginners guide for front-end developers to create amazing conceptual diagrams

If you are a front-end developer and visual learner who is interested in learning what goes into making conceptual diagrams, then this article is for you.

Conceptual diagrams are a visual way to show how things work. These diagrams help us simplify and make sense of technical ideas of the front-end ecosystem.

When I started my diagramming journey back in 2015, I didn’t know I was creating conceptual diagrams! Being a visual learner, diagrams were simply a tool for me to capture and organise what I was learning - or I should say ‘not learning’ - because I could easily see the knowledge gaps in my learning.

Diagramming encouraged better understanding of what I was learning. With that in mind, I kept on creating similar diagrams as I progressed from Salesforce to Laravel to Vue to Nuxt - and everything in-between.

Over time, I learned that my diagrams matched very close to conceptual diagrams. I taught myself what conceptual diagrams were and made required adjustments to make them more technical and fit into the front-end stream.

As a front-end developer, I use these diagrams as:

• Learning and teaching resource: Nuxt lifecycle hooks
• Project planning tool: Component tree | Visualising project directories
• Visual documentation: VuePress Theme Blog Development

Building blocks

Conceptual diagrams have two key building blocks: concepts and connecting lines with words.

Concepts

Concepts can be defined as events or objects required for the main idea to exist or become complete.

Linking lines and words

Linking words are located on the lines that connect two concepts in a diagram. These connecting lines have an arrow head to indicate the flow. As for linking words, they are most likely to be verbs, like accepts, provides, includes, imports, etc., but they can also be phrases.

If I were to interpret the above example of JavaScript function, it would begin to look something like below👇 where concepts are presented in rectangle boxes. However, other shapes can be used to better visualise different types of events and objects.

Concepts with connecting words and lines

Now that we have a brief idea of key elements required to construct a diagram, we will take a look at the steps to create conceptual diagrams followed by an example.

Basic steps

1. Define a key topic
2. Identify key concepts
3. Link these concepts using connecting words to show the inter-relationships
4. Optimise spatial arrangement
5. Repeat step #2 to #4 till conceptually sound and accurate diagram is created

Example

Let’s take a simple example of JavaScript’s array prototype method called reduce and try to apply the above steps with details.

Step 1: Key topic

In this case, our key topic is the reduce method. We will try to show the technical formula of the reduce method and how it works.

Step 2: Key concepts identification

Before we get to the fun part of creating a diagram, it’s helpful to research and collect all the information on our key topic.

I often start with a concept that I am most likely to forget and build my list from there onwards. It helps me break down larger concepts and zoom in on a specific detail that I would like to visualise.

This brings us to the parking lot. Parking lot is a container where we store all the concept terms. It's only for our reference. This is from where we will move the concept terms into the diagram.

If you prefer, you can start thinking about where each concept term might fit into a diagram at the same time and arrange parking lot items accordingly from the start. I personally like freestyle brainstorming and research where I keep adding concept terms to the list without thinking about their final placement.

Here's the parking lot of the reduce method👇 diagram.

parking lot with list of concepts

We may not end up using all concepts we have listed, because the main goal here should be to organise knowledge around the key topic.

For example, it might be tempting to add how a JavaScript array works in this example since it’s related to the reduce method. However, it might just take the focus off from the reduce method. Therefore, use what's absolutely needed to explain the topic well, and eliminate concepts that may prevent comprehension of the main idea.

Step 3: Link concepts with connecting lines and words

In this step, we link two concepts using action verbs and show the interrelationship between the two. Good rule of thumb here is to find more concise and short verbs, as they will help the diagram read well.

For example:

1. reduce (method) accepts callbackfFn and initial value
2. callback fn provides previous value, current value, current index and array arguments
3. initial Val defaults to 0th element
4. initial Val can also be object, array, number or string

parking lot to conceptual diagram conversion

Also, it’s worth taking a note of how the diagram flows. We have the most generic concept at the top, while it gets specific as we move towards the bottom. This is a general guideline that will help us maintain the direction of our diagram.

As long as we have concepts and connections relevant to the main topic, we should be able to expand the diagram without losing track.

When working on a more complex topic, I’d recommend going back to the main topic again and again to make sure we are creating our diagram with a context in mind.

Step 4: Optimise spatial arrangement

This is quite an important step to fine tune our diagram. This is where all the magic happens!

Once we have everything in place, we would rearrange the concepts to try and come up with a proportionate, readable and more balanced structure of the diagram with minimal to no intersecting lines.

While we are trying to make our diagram look aesthetically pleasing, we can also make other adjustments in this step by adding:

• code-blocks to reinforce the concept of reduce method and callbackFn
• sticky notes to clarify something that might be easily misunderstood
• Legend for symbolic or repeated information to save space while leaving the meaning intact

fine-tune the diagram

Above example is a version. Yours might be different, maybe even more detailed! But I hope this example has given you some useful, practical insights into creating conceptual diagrams.

Wrap up

Conceptual diagrams are easy to create. They always evolve with your understanding of the topic. And eventually, they will help you become a better learner.

This is a brief, beginners guide to creating diagrams for the front-end developers. It outlines a brief theory of conceptual diagrams with an example. But there’s more to these diagrams than what I have covered in this article. Follow me @krutiepatel to get notified of my upcoming articles about creating diagrams.