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.
For example, to understand JavaScript function, we would need to know concepts like function keyword, parameters and return statement. Thinking further about parameters, they can be primitive or non-primitive values and so on.
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.
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
- Define a key topic
- Identify key concepts
- Link these concepts using connecting words to show the inter-relationships
- Optimise spatial arrangement
- 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.
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:
- reduce (method) accepts callbackfFn and initial value
- callback fn provides previous value, current value, current index and array arguments
- initial Val defaults to 0th element
- initial Val can also be object, array, number or string
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.
...being said that, you will come across topics that might require you to move away from the hierarchical structure. You can see the circular structure in this Nuxt context 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
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.
© 2020 Krutie Patel