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