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

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.

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

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.

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.

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.