The Official Guide to Mermaid.js

Knut Sveidqvist, Ashish Jain

• Publisher: Packt Publishing
• Year: 2021
• eBook ISBN: 9781801076258
• Edition: 1
• Topic: Computer Science
• Subtopic: Computer Science General
• Index: Computer Science

Get up to speed with using Mermaid diagrams to facilitate a seamless development workflow with the help of real-world examples and expert tips from the creators of the toolKey Features• Learn how to use and customize the different diagram types in Mermaid• Discover examples of how to add Mermaid to a documentation system• Use Mermaid with various tools available such as editors, wiki, and moreBook DescriptionMermaid is a JavaScript-based charting and diagramming tool that lets you represent diagrams using text and code, which simplifies the maintenance of complex diagrams. This is a great option for developers as they're more familiar with code, rather than using special tools for generating diagrams. Besides, diagrams in code simplify maintenance and ensure that the code is supported by version control systems. In some cases, Mermaid makes refactoring support for name changes possible while also enabling team collaboration for review distribution and updates.Developers working with any system will be able to put their knowledge to work with this practical guide to using Mermaid for documentation. The book is also a great reference for looking up the syntax for specific diagrams when authoring diagrams.You'll start by learning the importance of accurate and visual documentation. Next, the book introduces Mermaid and establishes how to use it to create effective documentation. By using different tools, editors, or a custom documentation platform, you'll also understand how to use Mermaid syntax for various diagrams. Later chapters cover advanced configuration settings and theme options to manipulate your diagram as per your needs.By the end of this book, you'll be well-versed with Mermaid diagrams and how they can be used in your workflows.What you will learn• Understand good and bad documentation, and the art of effective documentation• Become well-versed with maintaining complex diagrams with ease• Discover how to draw different types of Mermaid diagrams such as flowcharts, class diagrams, Gantt charts, and more• Implement Mermaid diagrams in your workflows• Understand how to set up themes for a Mermaid diagram or an entire site• Get to grips with setting up a custom documentation systemWho this book is forThis book is for content generators such as technical writers, developers, architects, business analysts, and managers who want to learn effective documentation or how to effectively represent diagrams using simple text code snippets and extract them. Familiarity with documentation using Markdown will be helpful, but not necessary.

Section 1: Getting Started with Mermaid

This section introduces Mermaid to the readers, where they will understand about effective documentation, what Mermaid is and why it came into being, and how to use it. It also covers all the important concepts needed to understand and use different configuration options, and how to change the default styles and override the theme to make their diagram look better.

This section comprises the following chapters:

• Chapter 1, The Art of Documentation with Mermaid
• Chapter 2, How to Use Mermaid
• Chapter 3, Mermaid Versions and Using the Live Editor
• Chapter 4, Modifying Configurations with or without Directives
• Chapter 5, Changing Themes and Making Mermaid Look Good

Chapter 1: The Art of Documentation with Mermaid

There is a wealth of information online on how to create Mermaid diagrams. This information is great; all you need to know can be found on the internet, but only if you have the time and patience, and also know what to look for.

In this book, we aim to create a definite guide where you will learn how to use Mermaid to create good documentation. Creating good documentation is not only about tools, though good tools help a lot. We will provide some opinionated pointers that will help you in your documentation efforts. You will, of course, gain in-depth information on how to use Mermaid, the diagram types, syntax configuration, and so on. You will also learn about different ways of using Mermaid which is a bit harder to find online; for example, we will explain how to use Mermaid together with Markdown and how to set up documentation systems in different ways.

In this chapter, you will learn about the importance of documentation, explore the different aspects of documentation in software development, and understand the key differences between lousy documentation and good documentation that is worth writing and reading. You will gain an understanding of the concepts surrounding efficient documentation and how to choose a documentation system.

We will also introduce Mermaid. You will learn how and why it came into existence, and how you can create efficient documentation using Mermaid and Markdown.

In this chapter, we will cover the following topics:

• Understanding the importance of documentation
• Understanding the difference between Good and Bad documentation
• Introducing Mermaid with Markdown

Understanding the importance of documentation

Documentation, in simple words, means any written material, with or without supporting illustrations. It is used to list, explain, and guide the reader through certain features of a product, a process, a smaller part of a bigger system, or literally anything worthy of taking notes about. It helps with easier visualization and helps us understand the problem(s) at hand since all the important points are recorded.

In terms of the software industry, documentation plays a crucial role right from the start of the project, and this continues even after the software is released. It doesn't matter whether it is a small project or a big enterprise-level product. It may be created by a small team of developers, or by a big, multi-vendor distributed team across the globe.

In all these cases, we require some form of written, documented material, starting with requirement specifications, solution designs, the flow of information, and more. This makes software development and its intended use easier in the different phases. Documentation is needed to describe the various functionalities of the software so that we can collect and collate all the product-related information at a single point. This makes it easier for the different stakeholders involved, such as business management, product owners, developers, testers, and so on, to discuss and share all the major questions that may arise during the entire life cycle.

There are many reasons why documentation is essential. The main arguments that will be made here surround development and process documentation but can also be applied to other contexts. The following subsections highlight some of the reasons why you should pay more attention to documentation.

Clear definition of requirements and scope

Imagine you are building the house of your dreams without any blueprints or initial specifications. Without these, you don't know the plan of the house or what the size of the rooms will be. The instructions that go to the building crew arrive on an ad hoc basis. The building crew might be rotating their shifts, which means questions will be asked at random times. In the end, do you think the house will end up looking like your vision?

A similar thing happens in software development if we don't have clear and concise documents establishing the business goals and requirements. Even though the requirements might not be finished before development starts, as in the preceding example, the work with requirements that goes on during the development cycle needs to be reflected in the documentation. If there is no documentation, then the developers may go astray from the core functionality that the product is expected to deliver during the development life cycle. Having this aspect documented ensures that all the different stakeholders involved are moving toward achieving the same goal. And if anyone forgets what was discussed or if someone new arrives in the team, they can always go back to the documented material for reference and validation.

The importance of clear definition and scope applies as much to agile development processes as they do in traditional development processes. When using agile, there are still requirements that should be documented. If we look at Scrum, the most widespread agile process, as an example, we have requirements documented in a backlog, with more detailed requirements the closer they are to being worked upon. We have a scope defined in work chunks called sprint plans, again with more details in the upcoming sprint compared to sprints down the line. Not all this might be documented in traditional documents, but it is still documentation, be it post-it notes on a wall or a backlog in a web-based requirement tool.

Assisting in testing and maintenance

Let's once again use the example of your dream house. Once it has been built, documentation would be used to verify the various aspects of the house, that it looks and functions in the same manner as you intended it to. We might need the blueprint, based on which we can say whether all the specifications have been met. If something is not operating properly, we can compare it against the blueprint, identify the flaw, and ask the builder to rectify the problem. A few years down the line, when a pipe breaks in the bathroom, the contractor who was hired to fix the issue can look at the blueprint to know in which walls the pipes can be found in.

Similarly, once the development phase is complete and the product has gone through a testing phase, the tester will need to know what to expect of the system. The tester will then prepare the test plans accordingly. In the same manner, once the software has gone into production, the support team needs to know how the system should behave under different use cases. So, by comparing it with the expected behavior, they can identify potential bugs quickly. This example has shown that documentation plays a major role, even after the release.

Better collaboration and teamwork

Creating software is a team effort. As such, when you pass tasks between different team members, it is vital to have a common view of the work to be done. Different members might have different ideas on how to implement different functionalities and what to implement, but everybody needs to understand the same requirements and processes to share a common view of what needs to be accomplished, and how it should be done. Getting everyone to understand the common goal is where documentation helps.

Two developers can share a design specification of a system by using an API between two components. One developer could implement the API, while the other developer could start implementing code for consuming the API. This parallel work requires a common view of the details in the API, from its general functionality all the way to the details of the method names in the API. A developer can read/write a design specification, describing how a system/module should work, and then a tester can read the same design specification when creating a suite of tests for that system/module. This is a good way of collaborating, given that you have good documentation that is being adhered to.

In today's world, where the whole team is distributed across different parts of the world, there is a high possibility that different members with different backgrounds can interpret information differently. Having a central piece of a written document that can be referred to when solving a major issue can minimize confusion and ambiguity. This documentation assists in better collaboration.

Increases the team's competencies

You must have heard of the phrase, "Don't put all your eggs in the same basket." Well, why do they say that? It is quite simple. Imagine you are super hungry and are dreaming of a perfectly cooked egg for breakfast. If all the eggs are in just one basket, if the basket were to be dropped and the eggs smashed, you would be left with nothing but an empty stomach. What you need to do is distribute the eggs so that even if one basket falls, you still have enough eggs to enjoy your breakfast.

This is similar in the case of the software development world, which brings us to the next reason why documentation is important: it is not efficient for just one person to have all the knowledge that is required. If that person is not available for any reason, then the work slows down or stops while the team is trying to figure out the problem. However, if that knowledge was documented, then the progress of figuring out a solution to a problem is usually much quicker than reverse engineering or guessing.

Preserve good procedures in the organizational memory

When we have well-written documentation for a successful project, it serves as a reservoir of all the good processes and decisions that contributed to our success, which can then be derived from and applied to a new project. It also throws light on what didn't work and where improvements can be made; this can help in cutting down the development time for the new project as you have a template of what works and what doesn't work. Everyone loves to succeed and apply what they've learned to their next project, and effective documentation helps in facilitating this.

For example, consider that your organization has finished a project on time and within budget for an important client. During the project, a special planning method was used, and several risks were identified and handled. In the project documentation, the risks, their mitigations, and their special planning procedures were covered. Later, another client comes along with a similar project, but unfortunately, the project team that han...

Table of contents

• The Official Guide to Mermaid.js
• Contributors
• Preface
• Section 1: Getting Started with Mermaid
• Chapter 1: The Art of Documentation with Mermaid
• Chapter 2: How to Use Mermaid
• Chapter 3: Mermaid Versions and Using the Live Editor
• Chapter 4: Modifying Configurations with or without Directives
• Chapter 5: Changing Themes and Making Mermaid Look Good
• Section 2: The Most Popular Diagrams
• Chapter 6: Using Flowcharts
• Chapter 7: Creating Sequence Diagrams
• Chapter 8: Rendering Class Diagrams
• Chapter 9: Illustrating Data with Pie Charts and Understanding Requirement Diagrams
• Section 3: Powerful Diagrams for the Advanced User
• Chapter 10: Demonstrating Connections Using Entity Relationship Diagrams
• Chapter 11: Representing System Behavior with State Diagrams
• Chapter 12: Visualizing Your Project Schedule with Gantt Chart
• Chapter 13: Presenting User Behavior with User Journey Diagrams
• Appendix :Configuration Options
• Other Books You May Enjoy