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

eBook
€8.99 €26.99
Paperback
€32.99
Subscription
Free Trial
Renews at €18.99p/m

What do you get with Print?

Product feature icon Instant access to your digital eBook copy whilst your Print order is Shipped
Product feature icon Colour book shipped to your preferred address
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Product feature icon AI Assistant (beta) to help accelerate your learning
OR
Modal Close icon
Payment Processing...
tick Completed

Shipping Address

Billing Address

Shipping Methods
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
Estimated delivery fee Deliver to Cyprus

Premium delivery 7 - 10 business days

€32.95
(Includes tracking information)

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 Print?

Product feature icon Instant access to your digital eBook copy whilst your Print order is Shipped
Product feature icon Colour book shipped to your preferred address
Product feature icon Download this book in EPUB and PDF formats
Product feature icon Access this title in our online reader with advanced features
Product feature icon DRM FREE - Read whenever, wherever and however you want
Product feature icon AI Assistant (beta) to help accelerate your learning
OR
Modal Close icon
Payment Processing...
tick Completed

Shipping Address

Billing Address

Shipping Methods
Estimated delivery fee Deliver to Cyprus

Premium delivery 7 - 10 business days

€32.95
(Includes tracking information)

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
€18.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
€189.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
€264.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 €26.97 €76.97 €50.00 saved
Automating Workflows with GitHub Actions
€32.99
The Official Guide to Mermaid.js
€32.99
TypeScript 4 Design Patterns and Best Practices
€27.99
Total €26.97€76.97 €50.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 the delivery time and cost of print book? Chevron down icon Chevron up icon

Shipping Details

USA:

'

Economy: Delivery to most addresses in the US within 10-15 business days

Premium: Trackable Delivery to most addresses in the US within 3-8 business days

UK:

Economy: Delivery to most addresses in the U.K. within 7-9 business days.
Shipments are not trackable

Premium: Trackable delivery to most addresses in the U.K. within 3-4 business days!
Add one extra business day for deliveries to Northern Ireland and Scottish Highlands and islands

EU:

Premium: Trackable delivery to most EU destinations within 4-9 business days.

Australia:

Economy: Can deliver to P. O. Boxes and private residences.
Trackable service with delivery to addresses in Australia only.
Delivery time ranges from 7-9 business days for VIC and 8-10 business days for Interstate metro
Delivery time is up to 15 business days for remote areas of WA, NT & QLD.

Premium: Delivery to addresses in Australia only
Trackable delivery to most P. O. Boxes and private residences in Australia within 4-5 days based on the distance to a destination following dispatch.

India:

Premium: Delivery to most Indian addresses within 5-6 business days

Rest of the World:

Premium: Countries in the American continent: Trackable delivery to most countries within 4-7 business days

Asia:

Premium: Delivery to most Asian addresses within 5-9 business days

Disclaimer:
All orders received before 5 PM U.K time would start printing from the next business day. So the estimated delivery times start from the next day as well. Orders received after 5 PM U.K time (in our internal systems) on a business day or anytime on the weekend will begin printing the second to next business day. For example, an order placed at 11 AM today will begin printing tomorrow, whereas an order placed at 9 PM tonight will begin printing the day after tomorrow.


Unfortunately, due to several restrictions, we are unable to ship to the following countries:

  1. Afghanistan
  2. American Samoa
  3. Belarus
  4. Brunei Darussalam
  5. Central African Republic
  6. The Democratic Republic of Congo
  7. Eritrea
  8. Guinea-bissau
  9. Iran
  10. Lebanon
  11. Libiya Arab Jamahriya
  12. Somalia
  13. Sudan
  14. Russian Federation
  15. Syrian Arab Republic
  16. Ukraine
  17. Venezuela
What is custom duty/charge? Chevron down icon Chevron up icon

Customs duty are charges levied on goods when they cross international borders. It is a tax that is imposed on imported goods. These duties are charged by special authorities and bodies created by local governments and are meant to protect local industries, economies, and businesses.

Do I have to pay customs charges for the print book order? Chevron down icon Chevron up icon

The orders shipped to the countries that are listed under EU27 will not bear custom charges. They are paid by Packt as part of the order.

List of EU27 countries: www.gov.uk/eu-eea:

A custom duty or localized taxes may be applicable on the shipment and would be charged by the recipient country outside of the EU27 which should be paid by the customer and these duties are not included in the shipping charges been charged on the order.

How do I know my custom duty charges? Chevron down icon Chevron up icon

The amount of duty payable varies greatly depending on the imported goods, the country of origin and several other factors like the total invoice amount or dimensions like weight, and other such criteria applicable in your country.

For example:

  • If you live in Mexico, and the declared value of your ordered items is over $ 50, for you to receive a package, you will have to pay additional import tax of 19% which will be $ 9.50 to the courier service.
  • Whereas if you live in Turkey, and the declared value of your ordered items is over € 22, for you to receive a package, you will have to pay additional import tax of 18% which will be € 3.96 to the courier service.
How can I cancel my order? Chevron down icon Chevron up icon

Cancellation Policy for Published Printed Books:

You can cancel any order within 1 hour of placing the order. Simply contact customercare@packt.com with your order details or payment transaction id. If your order has already started the shipment process, we will do our best to stop it. However, if it is already on the way to you then when you receive it, you can contact us at customercare@packt.com using the returns and refund process.

Please understand that Packt Publishing cannot provide refunds or cancel any order except for the cases described in our Return Policy (i.e. Packt Publishing agrees to replace your printed book because it arrives damaged or material defect in book), Packt Publishing will not accept returns.

What is your returns and refunds policy? Chevron down icon Chevron up icon

Return Policy:

We want you to be happy with your purchase from Packtpub.com. We will not hassle you with returning print books to us. If the print book you receive from us is incorrect, damaged, doesn't work or is unacceptably late, please contact Customer Relations Team on customercare@packt.com with the order number and issue details as explained below:

  1. If you ordered (eBook, Video or Print Book) incorrectly or accidentally, please contact Customer Relations Team on customercare@packt.com within one hour of placing the order and we will replace/refund you the item cost.
  2. Sadly, if your eBook or Video file is faulty or a fault occurs during the eBook or Video being made available to you, i.e. during download then you should contact Customer Relations Team within 14 days of purchase on customercare@packt.com who will be able to resolve this issue for you.
  3. You will have a choice of replacement or refund of the problem items.(damaged, defective or incorrect)
  4. Once Customer Care Team confirms that you will be refunded, you should receive the refund within 10 to 12 working days.
  5. If you are only requesting a refund of one book from a multiple order, then we will refund you the appropriate single item.
  6. Where the items were shipped under a free shipping offer, there will be no shipping costs to refund.

On the off chance your printed book arrives damaged, with book material defect, contact our Customer Relation Team on customercare@packt.com within 14 days of receipt of the book with appropriate evidence of damage and we will work with you to secure a replacement copy, if necessary. Please note that each printed book you order from us is individually made by Packt's professional book-printing partner which is on a print-on-demand basis.

What tax is charged? Chevron down icon Chevron up icon

Currently, no tax is charged on the purchase of any print book (subject to change based on the laws and regulations). A localized VAT fee is charged only to our European and UK customers on eBooks, Video and subscriptions that they buy. GST is charged to Indian customers for eBooks and video purchases.

What payment methods can I use? Chevron down icon Chevron up icon

You can pay with the following card types:

  1. Visa Debit
  2. Visa Credit
  3. MasterCard
  4. PayPal
What is the delivery time and cost of print books? Chevron down icon Chevron up icon

Shipping Details

USA:

'

Economy: Delivery to most addresses in the US within 10-15 business days

Premium: Trackable Delivery to most addresses in the US within 3-8 business days

UK:

Economy: Delivery to most addresses in the U.K. within 7-9 business days.
Shipments are not trackable

Premium: Trackable delivery to most addresses in the U.K. within 3-4 business days!
Add one extra business day for deliveries to Northern Ireland and Scottish Highlands and islands

EU:

Premium: Trackable delivery to most EU destinations within 4-9 business days.

Australia:

Economy: Can deliver to P. O. Boxes and private residences.
Trackable service with delivery to addresses in Australia only.
Delivery time ranges from 7-9 business days for VIC and 8-10 business days for Interstate metro
Delivery time is up to 15 business days for remote areas of WA, NT & QLD.

Premium: Delivery to addresses in Australia only
Trackable delivery to most P. O. Boxes and private residences in Australia within 4-5 days based on the distance to a destination following dispatch.

India:

Premium: Delivery to most Indian addresses within 5-6 business days

Rest of the World:

Premium: Countries in the American continent: Trackable delivery to most countries within 4-7 business days

Asia:

Premium: Delivery to most Asian addresses within 5-9 business days

Disclaimer:
All orders received before 5 PM U.K time would start printing from the next business day. So the estimated delivery times start from the next day as well. Orders received after 5 PM U.K time (in our internal systems) on a business day or anytime on the weekend will begin printing the second to next business day. For example, an order placed at 11 AM today will begin printing tomorrow, whereas an order placed at 9 PM tonight will begin printing the day after tomorrow.


Unfortunately, due to several restrictions, we are unable to ship to the following countries:

  1. Afghanistan
  2. American Samoa
  3. Belarus
  4. Brunei Darussalam
  5. Central African Republic
  6. The Democratic Republic of Congo
  7. Eritrea
  8. Guinea-bissau
  9. Iran
  10. Lebanon
  11. Libiya Arab Jamahriya
  12. Somalia
  13. Sudan
  14. Russian Federation
  15. Syrian Arab Republic
  16. Ukraine
  17. Venezuela