Search icon CANCEL
Subscription
0
Cart icon
Your Cart (0 item)
Close icon
You have no products in your basket yet
Arrow left icon
Explore Products
Best Sellers
New Releases
Books
Videos
Audiobooks
Learning Hub
Conferences
Free Learning
Arrow right icon
The Official Guide to Mermaid.js
The Official Guide to Mermaid.js

The Official Guide to Mermaid.js: Create complex diagrams and beautiful flowcharts easily using text and code

Arrow left icon
Profile Icon Knut Sveidqvist Profile Icon Jain
Arrow right icon
$19.99 per month
Full star icon Full star icon Full star icon Full star icon Half star icon 4.3 (7 Ratings)
Paperback Sep 2021 492 pages 1st Edition
eBook
$9.99 $35.99
Paperback
$43.99
Subscription
Free Trial
Renews at $19.99p/m
Arrow left icon
Profile Icon Knut Sveidqvist Profile Icon Jain
Arrow right icon
$19.99 per month
Full star icon Full star icon Full star icon Full star icon Half star icon 4.3 (7 Ratings)
Paperback Sep 2021 492 pages 1st Edition
eBook
$9.99 $35.99
Paperback
$43.99
Subscription
Free Trial
Renews at $19.99p/m
eBook
$9.99 $35.99
Paperback
$43.99
Subscription
Free Trial
Renews at $19.99p/m

What do you get with a Packt Subscription?

Free for first 7 days. $19.99 p/m after that. Cancel any time!
Product feature icon Unlimited ad-free access to the largest independent learning library in tech. Access this title and thousands more!
Product feature icon 50+ new titles added per month, including many first-to-market concepts and exclusive early access to books as they are being written.
Product feature icon Innovative learning tools, including AI book assistants, code context explainers, and text-to-speech.
Product feature icon Thousands of reference materials covering every tech concept you need to stay up to date.
Subscribe now
View plans & pricing
Table of content icon View table of contents Preview book icon Preview Book

The Official Guide to Mermaid.js

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 handled the successful project is not available. Here, the documentation from the successful project can be used as a starting point for the new project; the special planning procedures can then be used during the project planning phase and the risk documentation can be used as input for the risk planning phase. Thanks to good documentation, the new project has a much higher chance of success than it would have had otherwise.

Documentation is important when working with agile development processes

Many people utilizing agile development have the misconception that you don't need any documentation while doing agile development. We would say that you need documentation in agile development as much as in any other paradigm. You do need to be smart about how you write your documentation, though. The agile manifesto states that there should be a focus on working software over comprehensive documentation. However, you could argue that good documentation helps to create working software, so this is completely in line with the agile manifesto.

Before we move on to the next section, let's quickly recap what you have learned so far. In this section, we have learned what documentation is, as well as its importance. We learned how crucial documentation can be, particularly in the software industry, from the inception of the product to after its release. This promotes better collaboration and teamwork among team members and helps in resolving dependencies on one individual. With good documentation available for previous projects, it becomes easier to understand what works and what doesn't, and you can get a good head start with new, upcoming projects. At this point, you are aware of why documentation plays an important part in the entire software life cycle. In the next section, we will go a bit deeper and understand the subtle differences between good documentation and bad documentation. We will also discuss how to achieve efficient documentation.

Understanding Good, Bad, and Efficient documentation

In this section, we will reflect on the concept of good documentation. In practice, what counts as good and bad documentation is not black or white and will differ between organizations.

Good documentation is documentation that is read and brings value, such as helping to create working software, while bad documentation is documentation that does not help in such efforts. Let's look at some documentation aspects so that we can understand how to improve on the documentation process to make it better. To classify a piece of documentation as good or bad, you need to ask the following questions:

  • What level of detail is required? At some point, the information might stop being useful and instead become cumbersome.
  • Does longer always mean better? Does documentation always need to be lengthy in order to be better? Well, maybe in some cases, but not always. You could argue that you should only pack in as much documentation as you are willing to maintain.
  • How hard is the process of documentation? How many steps are there to creating or updating the documentation? How difficult is each step? This heavily affects the efficiency of the documentation.
  • Do we have the right tools? Having the right tools is critical for any task, and this is the case for writing documentation. By having the right tools, the documentation cost can go down, and the quality can go up.
  • Do we have enough time and resources? As with everything else, documentation takes time and effort. You can't expect to have an optimum output and quality if, in a team of 10 developers, only one is tasked with writing the documents.
  • How often is the documentation being used? When you are writing a piece of documentation, it is important to understand how often it will be used. The information that is contained in the documentation should be relevant, and also add some value to the team, so that it is being used frequently. It is very important to document correct, up-to-date information – the information the organization will need to read about at later stages. This, combined with easy access to the documentation, is key to successful documentation.

We can elaborate more on these questions by exploring them in the context of bad documentation and good documentation.

What is bad documentation?

Based on the previous questions, let's look at what indicates bad documentation:

  • Detail: Too much detail is not always good. If you write about every bug, feature, loophole, and hiccup, it will become overwhelming for the users to find the primary functionality, as they will be lost in all this excessive information.
  • Length: Generally, there is an incorrect notion with documentation that the longer it is, the better it will be. Following this, you may think that all the information in your document is important, but your readers may not appreciate it if the document, for instance, is over 500 pages long.
  • Process: If the overall process of modifying and adding information to the documentation is too cumbersome and painful, and also requires a lot of steps and checks, then it stands to reason that the process will be expensive and, naturally, the contribution will be uninspired.
  • Tools: Having too many tools to maintain your documentation can affect efficiency and distract the developer. For example, if we have a separate tool for diagram creation, another tool for text formatting, and yet another tool for controlling versions, then all this adds to the complexity involved in writing documentation.
  • Allocated Time and Resources: With so much at stake and having learned about the importance of documentation, if you decide to rush through it so that you can add it right at the end, and not plan it in time, this will result in bad documentation. Imagine that you are part of a big team with only one person responsible for writing about everything in a limited period. If this happens, the overall quality will degrade.
  • Relevance and Frequency: Most of the people within the IT industry, at some point in their career, have needed to spend a few days writing a document they know no one will read, just to be able to check some box in some process. This is a clear example of wasted time, resources, and energy, especially today, when so many are striving to use agile methods. This is also referred to as bad documentation in this book.

What is good documentation?

Good documentation simplifies the complexity of everything, and doing so in fewer words makes it even better. Let's look at what is considered good documentation, based on the previous questions:

  • Detail: Keep the documentation to the point, short, and crisp. If you need to express detailed scenarios for loopholes or dirty tricks, create a separate manual for that. The readers of documentation want to find what they are looking for quickly; otherwise, they will not be interested in reading it further.
  • Length: Does longer always mean better? Well, this is not always true. A 500+ page documentation may scare the reader, whereas a shorter variant of 150 pages may be appreciated more. If all the pages are important and required, then break them into smaller chunks that are relatable and easier to search, instead of one big, mammoth book. Note that if the short version excludes vital information, the longer version might be the better version. So, the answer to the question "Does longer always mean better?" is… only when it needs to be longer. Software documents should be as brief as possible.
  • Process: A good process is a seamless one that does not require a lot of superfluous checks and automates the steps that can be automated. Examples of steps that should be automated include maintaining versions and auto-updating within the build. An easy process for writing and modifying documentation not only saves time but is more encouraging and allows contributors to have more fun while they write. After all, the most common problem with documentation is getting people to write it. A slick, fun process can greatly help with this!
  • Tools: Markdown and Mermaid are a good combination for writing documentation. This provides the biggest advantage for technical writers such as developers, business analysts, testers, product owners, and so on. They are familiar with simple language instructions or code-like syntax for drawing diagrams.
  • Allocated Time and Resource: To have efficient and good quality documentation, you should plan ahead, given that you have enough time and resources, so that it becomes a collaborative effort throughout the development process rather than an individual's pain.
  • Relevance and Frequency: Writing good documentation is also much more rewarding than writing bad documentation. Compared to the preceding example, writing a document that people around you need and are willing to read attributes to good documentation. You might get positive feedback, questions about sections that are unclear, and requests for additional information. This document has an active audience and helps people with their work.

What is Efficient Documentation?

Writing documentation, locating it to read, and keeping it up to date can be quite challenging, especially in an era when the allotted time for most tasks seems to become smaller and smaller with ever-increasing demands for higher efficiencies.

At this point, we know how crucial and valuable the skill of documenting your project properly is. Often, as developers, we tend to work on different projects, and if a project already has good documentation, then we will be happier, more comfortable, and understand the project quicker. But at the same time, a lot of people don't get equally as excited when they have to write technical documentation. We need to understand why.

Another common problem that many of us face is that even though the project has been documented, most of it is not relevant or is outdated. So, why do some developers struggle with writing and maintaining documentation, and can we do something about this? 

By understanding the guidelines of efficient documentation, you can make this process easier. You practice efficient documentation when the documentation you create and consume is in line with the following questions:

  • Is it distraction free? To be efficient means to do things in an organized manner, and to write documentation efficiently, you must be focused on the writing process. This means avoiding other distractions, such as juggling different tools and maintaining formatting for images, text, charts, and more. This is known as context switching.
  • Is it searchable and reachable? No matter how good your content is, if the documentation is difficult to access, then it will be a pain point to the readers. Ideally, all the different documents in a system must be easily accessible, indexed, and searchable, so that the readers can find what they're looking for. Apart from a documentation system that allows for finding the right document, we should always choose a documentation system that provides easy access throughout the entire document. It should contain quick links, a search utility, and navigation across the document so that it is easier for the reader to follow it, process it, and use it to the best of their abilities. Good documentation is scannable and short. We should avoid walls of text; instead, we should add illustrations such as graphs and diagrams, since most people tend to think visually and prefer diagrams rather than long texts. The illustrations are also often used for reference.
  • Is it easy to access when something needs to be created or updated? It must be easy for the documentation to be added, modified, or removed. The overall process should be smooth. This would allow more time for writing the actual content.
  • Does it make it easy to see who made a change, what the change was, and when? It is important to see the timeline of the documentation and how it has evolved. As part of this process, we need to know what changes have been made, who made the changes, and when the change was made. This is helpful when you're clarifying that something new was discussed and added, and if validation from the author is needed; that is, to check the identity of who modified or added a particular change. In case of any confusion, you could reach out to the author and understand or validate why the change was needed.
  • Does it handle multiple simultaneous versions of the documentation? For instance, one section might differ between different system releases and what is currently under development. A better approach from the developer's perspective is to have a documentation system that lets you commit parts of documentation to version control systems (such as Git and SVN), similar to how code is managed.

Guidelines for setting up Good Documentation

In software development, to make the overall process of documentation easier, faster, and efficient, use the following guidelines:

  • Choose simple formatting rules and adhere to them: You should choose a formatting style for your documentation that covers the most necessary requirements and works well for the entire team. When you have a set of simple formatting and styling rules that everyone adheres to, it is much easier to combine their documentation. An example would be if you choose Markdown as the style for your documentation. Then, regardless of which editor everyone uses, as long as they write the necessary Markdown syntax, the output will be similar throughout.
  • Make it visual: Add diagrams, pictures, and graphs as they make the documentation much more engaging and interesting. Using visual elements like this can help you explain a complex scenario, while making information easier to understand compared to just sentences. Adding visual elements wherever relevant is a good practice you should follow. The following image is an example to showcase the power of adding graphics to your text:
Figure 1.1 – An image illustrating the illustrative properties of an illustration

Figure 1.1 – An image illustrating the illustrative properties of an illustration

Here, you can see that the majority of the top GitHub projects contain full documentation and none of the projects have no documentation. This point is much clearer to the reader from the pie chart than if we were to just use text.

  • Should support collaboration: You should choose a documentation system that supports collaborative documentation. Most of us work in a team or a group, and it is important for each of them to be able to contribute and access the documentation.
  • Audience is key: To consider this, you need to understand who is going to read the document – is it the technical team, the business team, or somebody else? You need to make sure that the technical jargon and acronyms suit the target audience and their understanding of the topic; if the audience doesn't fully understand the jargon, it is not helping them, but instead making the document harder to understand. You should not assume everyone knows all the concepts you're talking about, and you don't want your readers to feel lost. Remember, we need to write to impress and serve our audience.
  • Share examples: It is important to share examples (whenever possible) with the audience, for them to understand certain concepts. With the help of an example, they can easily relate to applying the underlying concept. For example, in technical guides for a programming language, it would be very helpful to use code snippets as examples for the readers to follow along and practice with.
  • KISS principle: Much like the Keep It Simple, Stupid (KISS) design principle, you should keep the documentation simple and use short sentences.
  • Be mindful of spelling and grammar: As simple as it may appear, spelling and grammar is also an important element so that you have effective and efficient documentation. Poor spelling and grammar might confuse and distract the reader, to the extent that they can't assimilate and understand the text properly. These issues may look painfully obvious, yet are often ignored in the documentation. Grammar and spell-checking plugins could be your friends here.
  • Feedback matters: We are humans, and individuals think differently. No one is perfect, and we all make mistakes. Therefore, it is important to have a feedback mechanism in the documentation process, where positive and constructive feedback can be given to help us improve on the documentation.

Archiving Documentation

To overcome the problem of outdated and insignificant documentation, you should define proper rules for updating and archiving a document. Sometimes, an updated document affects the reader of the document in such a way that it conflicts with the old version. In such cases, it might be vital to make sure that the old version of the documentation is archived and only the new version remains in use. This could be a process description, a design specification, or similar.

When a newer version of a piece of software or a product is released, we need to update the documentation, but we also need to maintain older versions of the documentation as well, for those users who are using an older version of the software/product. Due to this, It is also important to maintain proper versioning of the documentation. Take Java versions, for example; for each new Java release, a new Java document version is introduced, but still, many people use older variants of Java. Due to this, support for those older variants of the Java documents must be present as well.

When it comes to regular minor releases, where only parts of the documentation are updated, version control for individual pages must be supported. If the rules are well-defined, this issue of irrelevant and old documentation can be mitigated to an extent.

Now, let's review what we've learned in this section before we move on to the next one. After learning about the importance of documentation, you learned about the key differences between bad documentation and good documentation that is worth writing and reading. You understood the concept of efficient documentation and the factors that drive how to achieve it. At this point, you are aware of the guidelines you must keep in mind before selecting a documentation system, as well as the best practices to follow for efficient documentation. Now that you've explored the good and bad aspects of documentation, you will learn about Mermaid.js and how it, along with Markdown, can help with efficient documentation.

Introducing Mermaid with Markdown

First, let's go over some background. The idea for Mermaid came about after I tried to make a small update to a diagram within a document, a task that ended up taking a surprising amount of time. It turned out that the source file for the diagram was nowhere to be found, so the diagram had to be redrawn from scratch. This made me wonder how we could have a complete document in a text format, with document text and images in the same text file. Due to this, we came up with Markdown in combination with a new utility for rendering diagrams from text. Later the same evening, I sat down in my living room to start this new side project – a new graph rendering library – while my kids were watching The Little Mermaid on TV. And from this, the somewhat whimsical name for the software was born: Mermaid.

Mermaid.js is a scripting language that lets you represent different types of diagrams as text. It uses a web browser to transform the diagram text into an SVG, rendering a graphical display of the information in the text. Mermaid.js lets you create various diagrams and flowcharts using only simple markup-like text. It is a free, open source, and easy-to-use JavaScript library. Mermaid.js lets you simplify documentation and helps you avoid using heavy, bulky tools to explain your ideas.

One of the core goals of Mermaid.js is to help you write your documentation and catch up with development. Typically, in today's world, development is done very quickly, but for some reason, the documentation is still lagging. It is this division between the progress of product development and the progress of documentation that Mermaid.js tries to address.

Often, it is difficult to express your code or use cases with just words in your documentation. There were no good solutions that supported declarative styles of writing in documentation, especially for developers; to many developers, it is much easier and more rewarding when they are writing documentation that is similar to coding. Having something that can transform a few lines of text into an elegant-looking diagram would make their lives easier, and this is exactly what Mermaid.js aims to do.

If you want to add Mermaid to your documentation process, you should know that Mermaid is versatile and can be used in many different ways, as follows:

  • Supports collaboration and sharing of diagrams via code snippets using the Mermaid Live Editor, where rendering happens by feeding code snippets to the Live Editor. This means that different members can alter the design in order to present an idea.
  • Can be integrated into a site or a product. This allows you to add the necessary diagram rendering capabilities to the site or product.
  • Can be integrated into a customized documentation system such as Docsify, Gatsby, and so on.
  • Can be used to generate simple standalone diagrams using the Mermaid Live Editor and the mermaid-cli.
  • With the help of custom plugins, it can be used in popular editors such as VSCode, Sublime Text, and so on. This way, charts and diagrams can be updated and changed, alongside the software project. This makes it easy to use and update documents.
  • It is open source and free to use. There's no need for bulky and pricey tools for creating diagrams.

Apart from that, Mermaid can already be used in many established document sources/wikis and tools such as Confluence, GitLab, and so on.

Not sold on Mermaid yet? Listen to the experts in the industry. Mermaid.js won the "Most exciting use of technology" award at the JavaScript Open Source awards 2019.

Diagrams are a powerful tool in the documentation toolbox, but diagrams need context, text with broader meaning, as well as explanations of the diagrams themselves. A great solution for this is to use Mermaid together with Markdown. In the next section, we explain why Mermaid and Markdown fit so well together.

Blending Mermaid with Markdown

Now that we know about efficient documentation, we should explore how we can achieve this by switching the method of documentation to a text-based form of documentation. This can be done by using Markdown combined with Mermaid.

Markdown is a lightweight markup language that allows you to create formatted text using a regular text editor. The format of Markdown allows the author to write text with formatting, but without tags that make the text harder to read. The greatness of Markdown is that it's easy to write, as well as easy to read. This formatted text can then easily be transformed into other formats, such as HTML, for publishing.

Now, let's look at why you should consider using Mermaid together with Markdown:

  • Minimize the number of distractions: We want to eliminate as many distractions as possible from documentation tasks. One such distraction is formatting – we have all been there, in that we've been distracted by a word processor's formatting possibilities and ended up focusing as much or more on how the document looked instead of focusing on writing the content. However, by writing the documentation in Markdown, we can avoid this. Mermaid helps you to create diagrams such as graphs, flowcharts, pie charts, and more directly from plain and simple text so that you don't need to switch to a different tool for them; Mermaid magically handles the layout, rendering, and formation of the diagram from the text input of the user.
  • Manage versions of the documentation: When adding or changing a feature, it is great to be able to keep the updates in the documentation regarding that change, together with the actual feature in the code. This is usually achieved by creating a branch in the code repository where the changes are performed in isolation from the production code. If the documentation is text-based and is added to the same repository location as the project code, then the documentation changes that have been made for new features can be handled the same way as the code. This means the process of pushing code to the central repository is similar to the way you will push your changes in the documentation. This makes life easier for a developer as they are already accustomed to this process. The text files for the documentation would be added/changed in the branch without affecting the published documentation, and when the code changes are merged, the corresponding documentation changes would also be tagged.
  • Stay focused with fewer context switches: Another way we can make documentation more efficient is by minimizing the context switches during development. Having the corresponding documentation in the same project as the code makes it possible to have a specification in one open tab in the integrated development environment (IDE) or editor while you're coding. This way, you have easy access to documentation while it's also available for modification. This scenario is quite easy to achieve and it doesn't take much effort to modify the document while implementing it. You might, for instance, want to add any missing details that surface during the implementation, adjust for some changes, or correct mistakes that have been identified at this stage.

With that, you have learned about the importance of using Mermaid together with Markdown. This combination sets up a powerful base for achieving efficient documentation since this approach aims at reducing any distractions, staying focused on writing the actual content rather than formatting, and supporting version control. In the next section, we'll look at how this combination can help when you're using a text-based documentation approach, along with your source code.

Blending text-based documentation with your code

If you have come so far as to have your documentation in text format by using Markdown and Mermaid, it could be a beneficial last step to move your documentation so that it resides close to your source code. This allows you to edit the documentation in the same context and environment where you code.

This helps reduce distractions when you're documenting as you wouldn't need to switch to another program; instead, you can continue in the same editor that you use for coding. Nor would you be distracted by a great number of formatting options, since most of the formatting will be handled automatically when you publish the documentation.

This setup also means that the documentation is available to read in your environment when you're writing code. This makes it quick and easy to modify documentation when something in the code has changed that needs to be reflected in the documentation; the threshold to actually perform that update is much lower if you need to perform a full context switch to make the change.

A context switch here would mean switching from your code editor, finding the right document, and updating it. Odds are that you lost the context of what you were doing in the source code before switching the documentation. With the documentation in your code project, you can simply open a tab in your editor that contains the documentation and update the documentation in parallel with the code.

Another example would be if you have the documentation in text form in a folder in your development project. Here, you could include the documentation folder when you are performing refactoring, such as a name change, and correct the documentation at the same time you're changing the code.

Making changes to the documentation in a Markdown file won't be any harder or more time-consuming than updating a code file.

When having the documentation text-based together with the code, it is effortless to practice efficient documentation:

  • There are no distractions when you're writing.
  • Easy to access when something needs to be created or updated.
  • Easy to access when you need to read your documentation or code.
  • Easy to see who made a change, what the change was, and when.
  • Handles multiple simultaneous versions of the documentation.

With that, you have learned that having the documentation as part of your code project is efficient and makes working on the documentation tie in well with the other development tasks such as coding. In the next section, we will explore why Mermaid fits so well with Markdown.

Advantages of using Mermaid with Markdown

The main advantage of using Mermaid with Markdown is that you are using a readable text format that can generate diagrams. This is very powerful and provides loads of advantages:

  • Using diagrams makes your documentation easier to understand, less intimidating, and, in effect, more informative. Having diagrams that can be changed as easily and quickly as your code is even better.
  • You are working with text, so, as a developer, you are already a master of editing text.
  • You can use your favorite text editor when writing the documentation.
  • The combined format is fairly simple and can be picked up by any developer.
  • You can keep the documentation in your code project while ensuring that you have efficient documentation, as highlighted in the previous section.
  • The documentation in text format is readable in any text editor without being published.
  • The process of formatting the documentation is separated from its content. By dodging this complexity, updates are easier to perform.
  • The documentation in this form is text-based, which makes revision handling using Git, subversion, or similar very easy.

As you can see, Mermaid fits well with Markdown, and the pair offer many advantages when used together. The simplicity of text provides a productive environment for creating documentation in a similar way to coding. Taking this further and having the documentation adjacent to your code is a great way of making sure the documentation stays updated, as well as readily available, when it's needed during development. This also means that we can have different versions of the documentation in the same way as we have different versions of the code. Also, don't forget that even though we are using text as our format, we can show meaningful and descriptive diagrams to the reader, thanks to Mermaid.

Now, let's look at what we've learned in this section. First, you learned what Mermaid.js is and why it came into existence. You then learned how blending Mermaid.js with Markdown syntax can be a powerful combination for effective and efficient documentation. Finally, you learned about the key benefits of using Mermaid.js in a documentation system, and briefly understood the different ways in which Mermaid.js can be applied.

Summary

That's a wrap for this chapter! Let's recollect what we've learned. First, we understood the importance of documentation. We gained general insights that helped us distinguish between bad documentation and good documentation. We also explored the concept of efficient documentation and how Mermaid and Markdown can be a perfect solution to achieve this. We then learned about key features that make developers love and adopt Mermaid.

In the next chapter, you will learn about the core crux of getting started with Mermaid. You will be exposed to different ways in which Mermaid can be used and applied, be it adding Mermaid to your website or using different tools and editors' plugins that have already integrated and adopted Mermaid. We will also look at how to work with documentation using Markdown and using our own custom Mermaid-powered documentation system with version control.

Left arrow icon Right arrow icon
Download code icon Download Code

Key benefits

  • 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 more

Description

Mermaid 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.

Who is this book for?

This 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.

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 system

Product Details

Country selected
Publication date, Length, Edition, Language, ISBN-13
Publication date : Sep 17, 2021
Length: 492 pages
Edition : 1st
Language : English
ISBN-13 : 9781801078023
Vendor :
ECMA International
Languages :
Tools :

What do you get with a Packt Subscription?

Free for first 7 days. $19.99 p/m after that. Cancel any time!
Product feature icon Unlimited ad-free access to the largest independent learning library in tech. Access this title and thousands more!
Product feature icon 50+ new titles added per month, including many first-to-market concepts and exclusive early access to books as they are being written.
Product feature icon Innovative learning tools, including AI book assistants, code context explainers, and text-to-speech.
Product feature icon Thousands of reference materials covering every tech concept you need to stay up to date.
Subscribe now
View plans & pricing

Product Details

Publication date : Sep 17, 2021
Length: 492 pages
Edition : 1st
Language : English
ISBN-13 : 9781801078023
Vendor :
ECMA International
Languages :
Tools :

Packt Subscriptions

See our plans and pricing
Modal Close icon
$19.99 billed monthly
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Simple pricing, no contract
$199.99 billed annually
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Choose a DRM-free eBook or Video every month to keep
Feature tick icon PLUS own as many other DRM-free eBooks or Videos as you like for just $5 each
Feature tick icon Exclusive print discounts
$279.99 billed in 18 months
Feature tick icon Unlimited access to Packt's library of 7,000+ practical books and videos
Feature tick icon Constantly refreshed with 50+ new titles a month
Feature tick icon Exclusive Early access to books as they're written
Feature tick icon Solve problems while you work with advanced search and reference features
Feature tick icon Offline reading on the mobile app
Feature tick icon Choose a DRM-free eBook or Video every month to keep
Feature tick icon PLUS own as many other DRM-free eBooks or Videos as you like for just $5 each
Feature tick icon Exclusive print discounts

Frequently bought together


Stars icon
Total $29.97 $100.97 $71.00 saved
Automating Workflows with GitHub Actions
$43.99
The Official Guide to Mermaid.js
$43.99
TypeScript 4 Design Patterns and Best Practices
$36.99
Total $29.97$100.97 $71.00 saved Stars icon
Banner background image

Table of Contents

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

Customer reviews

Top Reviews
Rating distribution
Full star icon Full star icon Full star icon Full star icon Half star icon 4.3
(7 Ratings)
5 star 42.9%
4 star 42.9%
3 star 14.3%
2 star 0%
1 star 0%
Filter icon Filter
Top Reviews

Filter reviews by




Reiner Eiteljörge Aug 31, 2022
Full star icon Full star icon Full star icon Full star icon Full star icon 5
Gute Einführung in Mermaid und didaktisch gut aufgebaut.Die Autoren verstehen es, den Leser von einem Thema zum nächsten mitzunehmen und z.B. die Sequenzdiagramme von einfach in Richtung komplizierter zu strukturieren und zu erläutern.Es ist gleichzeitig eine gute Darstellung der Möglichkeiten von Mermaid als auch eine Möglichkeit zum Nachschlagen, wenn das eigene Diagramm verbessert werden muss.Gutes Buch, klare Empfehlung.
Amazon Verified review Amazon
Rav Nov 05, 2021
Full star icon Full star icon Full star icon Full star icon Full star icon 5
The book is very detailed.The table of content is handy to quickly get what you are looking for.
Amazon Verified review Amazon
David Green Mar 12, 2022
Full star icon Full star icon Full star icon Full star icon Full star icon 5
This is a way of making drawings that are generated from text descriptions: flowcharts, class diagrams, state diagrams, and interaction diagrams are among the supported tools. I am using Typora which has mermaid.js inside and find the documentation useful. Ultimately, the configuration details are controlled by the text you enter and the platform's choices so there are some options that may not be achievable on all platforms although one can always go to mermaid.live and generate an image file.There were a few places where the example code and associated content don't match up but it is easy to work through. I think the UML drawings have the arrows backwards (on inheritance for example) but it is clear how to encode things correctly. Don't treat the book as the authority on the notation system but rather the drawing tool for you to craft your drawing with.
Amazon Verified review Amazon
Bhavya Sep 21, 2021
Full star icon Full star icon Full star icon Full star icon Empty star icon 4
First of all, I have been a fan of mermaid.js which is such a simple tool to draw flowcharts anywhere and makes an otherwise time consuming and boring task so easy and fun.I recently got to know about the book and after going through the digital version, I could actually grasp mermaid.js better. There is so much to it which is mentioned quite nicely in the book. I really liked the way chapters were organized and that there were really nice use case oriented illustrations. Although there could be some more real life examples (or guides), but the content is self-explanatory to help the user build diagrams by themselves.Would really like to thank the authors to make mermaid.js more accessible.
Amazon Verified review Amazon
Abhishek Sep 30, 2021
Full star icon Full star icon Full star icon Full star icon Empty star icon 4
Earlier I used to use gliphy or draw.io to create flow charts and sequence diagrams, but it was very time consuming. Then one of my colleague suggested me mermaidjs, I tried the tool and it was very intuitive. I explored various resources for learning the tool and found this book. This book is a one stop solution to learn mermaidjs.The best things about the book are:1. Every chapter is consice and has enough examples covered.2. The language used is simple.3. Each chapter is mostly independant, so you can straight away refer to the chapter for the diagram topic you want to use.4. The book is written by the mermaidjs creators themselves.In short this is a goto handbook for learning and using mermaidjs, highly recommend this one for anyone starting with mermaidjs.
Amazon Verified review Amazon
Get free access to Packt library with over 7500+ books and video courses for 7 days!
Start Free Trial

FAQs

What is included in a Packt subscription? Chevron down icon Chevron up icon

A subscription provides you with full access to view all Packt and licnesed content online, this includes exclusive access to Early Access titles. Depending on the tier chosen you can also earn credits and discounts to use for owning content

How can I cancel my subscription? Chevron down icon Chevron up icon

To cancel your subscription with us simply go to the account page - found in the top right of the page or at https://subscription.packtpub.com/my-account/subscription - From here you will see the ‘cancel subscription’ button in the grey box with your subscription information in.

What are credits? Chevron down icon Chevron up icon

Credits can be earned from reading 40 section of any title within the payment cycle - a month starting from the day of subscription payment. You also earn a Credit every month if you subscribe to our annual or 18 month plans. Credits can be used to buy books DRM free, the same way that you would pay for a book. Your credits can be found in the subscription homepage - subscription.packtpub.com - clicking on ‘the my’ library dropdown and selecting ‘credits’.

What happens if an Early Access Course is cancelled? Chevron down icon Chevron up icon

Projects are rarely cancelled, but sometimes it's unavoidable. If an Early Access course is cancelled or excessively delayed, you can exchange your purchase for another course. For further details, please contact us here.

Where can I send feedback about an Early Access title? Chevron down icon Chevron up icon

If you have any feedback about the product you're reading, or Early Access in general, then please fill out a contact form here and we'll make sure the feedback gets to the right team. 

Can I download the code files for Early Access titles? Chevron down icon Chevron up icon

We try to ensure that all books in Early Access have code available to use, download, and fork on GitHub. This helps us be more agile in the development of the book, and helps keep the often changing code base of new versions and new technologies as up to date as possible. Unfortunately, however, there will be rare cases when it is not possible for us to have downloadable code samples available until publication.

When we publish the book, the code files will also be available to download from the Packt website.

How accurate is the publication date? Chevron down icon Chevron up icon

The publication date is as accurate as we can be at any point in the project. Unfortunately, delays can happen. Often those delays are out of our control, such as changes to the technology code base or delays in the tech release. We do our best to give you an accurate estimate of the publication date at any given time, and as more chapters are delivered, the more accurate the delivery date will become.

How will I know when new chapters are ready? Chevron down icon Chevron up icon

We'll let you know every time there has been an update to a course that you've bought in Early Access. You'll get an email to let you know there has been a new chapter, or a change to a previous chapter. The new chapters are automatically added to your account, so you can also check back there any time you're ready and download or read them online.

I am a Packt subscriber, do I get Early Access? Chevron down icon Chevron up icon

Yes, all Early Access content is fully available through your subscription. You will need to have a paid for or active trial subscription in order to access all titles.

How is Early Access delivered? Chevron down icon Chevron up icon

Early Access is currently only available as a PDF or through our online reader. As we make changes or add new chapters, the files in your Packt account will be updated so you can download them again or view them online immediately.

How do I buy Early Access content? Chevron down icon Chevron up icon

Early Access is a way of us getting our content to you quicker, but the method of buying the Early Access course is still the same. Just find the course you want to buy, go through the check-out steps, and you’ll get a confirmation email from us with information and a link to the relevant Early Access courses.

What is Early Access? Chevron down icon Chevron up icon

Keeping up to date with the latest technology is difficult; new versions, new frameworks, new techniques. This feature gives you a head-start to our content, as it's being created. With Early Access you'll receive each chapter as it's written, and get regular updates throughout the product's development, as well as the final course as soon as it's ready.We created Early Access as a means of giving you the information you need, as soon as it's available. As we go through the process of developing a course, 99% of it can be ready but we can't publish until that last 1% falls in to place. Early Access helps to unlock the potential of our content early, to help you start your learning when you need it most. You not only get access to every chapter as it's delivered, edited, and updated, but you'll also get the finalized, DRM-free product to download in any format you want when it's published. As a member of Packt, you'll also be eligible for our exclusive offers, including a free course every day, and discounts on new and popular titles.