00:00:00.000
Ready for takeoff.
00:00:18.080
Hello! Thank you for coming. My name is Carolyn Cole, and I work at the Princeton University Library. This talk is about how I love Mermaid JS.
00:00:21.300
So, what is Mermaid JS? It's a tool that allows you to create diagrams as code. How awesome is that? You can create a diagram and keep it in your README file. Additionally, you can create a diagram along with your code, and when diagrams are treated as code, they become much easier to maintain.
00:00:29.580
As you can see here, GitHub will display your diagrams. All you need to do is add three backticks followed by 'mermaid', and then you can insert your diagram right into your README. I am really excited about that! The documentation for Mermaid is quite extensive, and it has been around since 2015, so it's been available for quite some time.
00:00:56.460
So, why would you want to utilize a diagram? This may seem obvious, but I like to use them for verifying understanding. People say a picture is worth a thousand words. As long as people can see it, it is. One thing to consider is accessibility; make sure you title your diagrams. You can document your systems for yourself or for future developers. I really appreciate documentation because diagrams help clarify explicit and implicit things that are not clearly stated in the requirements.
00:01:27.240
Here, I have some examples of diagrams that I have created for various systems. This is a state diagram, and you can see that it is embedded in my GitHub. While there may be a lot of text discussing the system's states, the state diagram visually illustrates how the different states flow into each other, making it much clearer how everything is connected.
00:01:43.680
This is a sequence diagram. It might seem relatively readable, but it's not entirely. However, the key takeaway is that the bar representing Alma is the trigger for every interaction in this system. Our system is in the middle, yet, notably, Alma does not directly touch it. Without this diagram, you would never know that Alma is actually the trigger for everything if you were simply reading the code.
00:02:11.500
I will now show you a flow diagram. While it may be challenging to read again, you can see how one input form interacts with eight different backends. The cool thing is that Mermaid can generate the diagram layout for you. I recently modified a flow from left to right to top down, and Mermaid managed the layout automatically without me needing to worry about it.
00:02:55.560
Now, I will move on to system requirements. The rest of this presentation will mostly be a demo where I create a Mermaid diagram. You don't need to know these requirements; I'm just using them to give context to my work. When I receive a set of requirements, I tend to ask similar questions like: 'What types of users are in the system?', 'What states can different objects go through?', and 'What external systems does my system work with?' Diagrams are excellent for bringing these questions to the forefront.
00:03:40.440
We are going to build a sequence diagram together. You will notice me making a lot of typos along the way—that's all part of the fun! I’m starting with a sequence diagram because it provides a high-level overview. However, you could use any of the diagrams we've discussed. The documentation for Mermaid is outstanding, but given its extensive nature, it can be a bit challenging to navigate, which is why I've created a cheat sheet.
00:04:11.940
Initially, I thought I would do this entirely in GitHub so you could see it there. However, due to network constraints, the preview doesn't always display well in GitHub. Therefore, we will do it here in my editor, but the nice thing is that many editors support Markdown. Thus, I can see my diagram as I'm creating it.
00:04:34.434
Let’s start with the first requirement: a user creates a new object, and I need to mint an ID in the system. As I change this diagram, you'll see additional elements being created. You'll notice that I created a new object, and now, you can see that Mermaid has instantly replaced it with the user and our system, while the tag has been changed to—'new object.' That's pretty cool! However, normally our user represents a person.
00:05:04.454
For accessibility purposes, I like to add a title to every image. So, one thing you can do is incorporate images representing different users. I am going to include that now, and the benefit is that you can differentiate between who's a human and who's a system in your diagram. Looking at my diagram, you can see I now have a humanoid user interacting with our system.
00:05:48.240
Another great feature is that you can set up participants with shortcut names. In this case, my system's name is somewhat lengthy. Therefore, I could just call it 'rsis' to simplify it. This way, I’m less likely to make typographical errors, although it can still happen! When I make a mistake, Mermaid alerts me with a syntax error, allowing me to identify what went wrong.
00:06:18.600
So we have established that a user created a new object and I need to mint an ID in System X. Let's create a participant for System X for reference. It's worth noting how Mermaid manages to lay everything out. You can see when I made an error while trying to create a participant, which resulted in two entries for 'Alma.' Mermaid lays everything out as per the code you've provided, but sometimes you must adjust it if it doesn't display as desired. We need to specify that System X will return to our system.
00:06:57.600
If I've got everything right, you can now see the clear structure of my diagram. We've recently created an object, and System X has returned the ID, and we will use this identification going forward. It’s not cumbersome at all to maintain and update diagrams in this way. The capability of having diagrams as code is convenient! Now we will explore further requirements to demonstrate additional features of Mermaid.
00:07:33.240
For instance, we must account for when a user updates the metadata on the object and whether we will update System X if it is relevant to that system. The user will also tell our system something. It’s essential to realize that users may not always communicate with System X, so we would look for alternatives. Mermaid has this feature called 'alternate,' which allows us to create branching logic in our diagrams, indicating when a choice is necessary.
00:08:28.260
This means that based on the user's input or action, we may need to update System X with new metadata related to their request. The next process involves notifying the curator whenever an object is ready for review. This indicates that distinct states exist for the object, leading us to consider adding roles such as a curator, which could also imply an extra layer in the approval process.
00:09:21.300
I am going to include a curator into our documentation and our diagram to see how that integrates. I’ll create a new participant for the curator while trying to manage the positioning in the diagram. Currently, the curator seems to fit between the user and the system in a manner that doesn’t fully capture the flow of how the process works. I'd prefer to reposition the curator’s role to reflect the proper order of operations.
00:09:55.080
The next step involves telling the system when the object is ready for review. To simplify matters, I will assume that we have direct access to the curator for this presentation. Still, it's essential to note that since this diagram is code, it can be adjusted anytime. For instance, if down the line we need to introduce different communication methods such as Slack or email, we’ll integrate those seamlessly.
00:10:30.000
For the last part of our process, we must recognize that the curator needs to approve the object before it is made public in the system. However, will the curator approve every single object? Likely not. Thus, we must account for feedback mechanisms, which suggests implementing some sort of feedback loop. Mermaid accommodates these scenarios well by allowing the inclusion of loops in the diagram.
00:11:10.680
I'm preparing to introduce a loop that represents the iterative nature of reviewing and approving or denying an object. I'll include alternate logic again to suggest that the object may not always be ready for approval. This creates a more dynamic view of the process and aids in clearly defining expectations.
00:12:14.190
As the curator passes decisions on those objects, whether they are approved or require adjustments, the system needs to capture and notify the user accordingly. The flow chart must outline these possibilities adequately: if the object is ready for approval, the system will mark it as public, thus informing the user of the action taken. If it is not ready, the system must prompt the user to correct any issues before resubmission.
00:13:01.740
Now we have a robust diagram illustrating the entire process, including complex flows and conditions! However, as visual diagrams can become congested, it's beneficial to implement grouping or theming, allowing for clearer presentation. I’ll add rectangles to distinguish two primary aspects of this process: creation and approval, making the diagram easier to comprehend.
00:13:56.130
Mermaid allows for different color coding as well. For easier visual distinction, I will use highlighter colors to demarcate each section further. Additionally, external themes exist that can enhance readability and visual appeal. I prefer the forest theme, reflecting my preferences. By inserting a simple line of code, I can change the global theme, impacting the entire diagram at once.
00:14:57.240
Now you can see the adjustments are reflected in the diagram, and the actors appear more vibrant. Each section of the diagram is characterized by its respective purpose. Overall, I hope that through this exploration, I have demonstrated the immense value Mermaid brings to crafting visual diagrams that are informative, accessible, and easy to maintain.
00:15:43.740
Thank you for attending my session, and I hope that you all share my admiration for Mermaid JS and feel inspired to use it as I do. The QR code displayed provides a link to the slides, should anyone wish to access them.
00:15:52.320
Now, if you have questions, please feel free to ask.
00:16:01.200
One question that arose was whether Mermaid is enabled by default on GitHub, and the answer is yes—absolutely! All you need to do is use the proper formatting in your Markdown files. Next, someone inquired about how easy it is to extend the Mermaid system, for which I can confirm that you can incorporate images in your diagrams. The system allows for exciting additions, and you can use icons or modify visual components as required.
00:17:02.760
I believe the cheat sheet is available, and because I work at a library, the resources I develop are generally open-source. It's easy for you to find and access the cheat sheet via the provided QR code, which will lead you to the slideshow.
00:17:28.920
Throughout the presentation, I've illustrated how we leverage Mermaid for swimlanes and documentation to convey our progress to supervisors. I fell in love with Mermaid when I first used it, thanks to a colleague who introduced it to me. Since then, I've been excited to share it with others, and I hope to encourage you all to appreciate its capabilities.
00:18:26.520
In response to a question about using additional icons, it has been confirmed that you can utilize Font Awesome icons in Mermaid. That’s another reason to love it! Thank you for your questions and participation throughout this session.
