The Official Guide to Mermaid.js E-Book

Knut Sveidqvist

• Herausgeber: Packt Publishing
• Kategorie: Fachliteratur
• Sprache: Englisch

Seitenzahl: 528

Veröffentlichungsjahr: 2021

Beschreibung

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.

Leseprobe

The Official Guide to Mermaid.js

Create complex diagrams and beautiful flowcharts easily using text and code

Knut Sveidqvist

Ashish Jain

BIRMINGHAM—MUMBAI

The Official Guide to Mermaid.js

Copyright © 2021 Packt Publishing

All rights reserved. No part of this book may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, without the prior written permission of the publisher, except in the case of brief quotations embedded in critical articles or reviews.

Every effort has been made in the preparation of this book to ensure the accuracy of the information presented. However, the information contained in this book is sold without warranty, either express or implied. Neither the author(s), nor Packt Publishing or its dealers and distributors, will be held liable for any damages caused or alleged to have been caused directly or indirectly by this book.

Packt Publishing has endeavored to provide trademark information about all of the companies and products mentioned in this book by the appropriate use of capitals. However, Packt Publishing cannot guarantee the accuracy of this information.

Group Product Manager: Pavan Ramchandani

Publishing Product Manager: Kaustubh Manglurkar

Senior Editor: Hayden Edwards

Content Development Editor: Aamir Ahmed

Technical Editor: Joseph Aloocaran

Copy Editor: Safis Editing

Project Coordinator: Ajesh Devavaram

Proofreader: Safis Editing

Indexer: Manju Arasan

Production Designer: Nilesh Mohite

First published: August 2021

Production reference: 1130821

Published by Packt Publishing Ltd.

Livery Place

35 Livery Street

Birmingham

B3 2PB, UK.

ISBN 978-1-80107-802-3

www.packt.com

To my mother and father, Ann-Margret and Carl-Birger Sveidqvist, for being there and for letting me follow my own path. To my wife, Maria, for helping me focus on the important things in life.– Knut Sveidqvist


To my parents, Geeta and Devendra Kumar Jain, for their sacrifices and for exemplifying the power of determination. To my loving wife, Palak, for her patience, support, and encouragement throughout the long process of writing this book. To Anant and Anubhav, for their love and inspiration.– Ashish Jain

Contributors

About the authors

Knut Sveidqvist has been in the software industry for over 20 years in roles spanning all the way from architecture to development through product ownership and managing development teams. A common theme in all these roles is the need for good documentation. This inspired Knut to create Mermaid and start the Mermaid open source project. The main goal with the project was and still is to make it more fun and efficient to write technical documentation. Ever since Knut created Mermaid, he has continued to work with the project and has a wealth of knowledge about Mermaid that he now wants to share with the developer community.

I want to start by thanking all the people who have used and loved Mermaid during the years. It is your support that makes this book possible. On a more personal note, I want to thank my friend, Fredrik Björkegren. At the age of 14 in the early eighties, I longed for a computer I could not afford. Together, we worked at a farm to be able to purchase a C64 home computer to share. It was through that computer that I found my love of programming. I am also grateful to my children, Hjalte, Vidar, Bjarke, and Ingvild, for their inspiration and encouragement. Finally, I want to thank my wife, Maria, for her patience during this process.

Ashish Jain has more than 8 years of experience as a technical lead and developer with a bachelor's degree in information technology. He started as a Java backend developer then moved to full-stack development. Within these roles, he worked on project documentation and other documented deliverables, where the need to have a simpler way to draw and integrate diagrams in documents was felt. His search ended with Mermaid, which impressed him enough to see him associate himself with the Mermaid project. He is an open source contributor and a part of the Mermaid core team.

I want to thank the people who have been dear to me and supported me, especially my parents, extended family, and close friends. Thanks also to the entire NAGP team at Nagarro for always motivating me to explore more, leading me to contribute to the open source community. I would like to thank Knut for presenting me with this opportunity, without whom this book would not be a reality.

We would also like to express our appreciation for the support, professionalism, and great collaboration from the Packt team in writing this book. Special thanks to Aamir and Hayden for their guidance and constructive feedback and Kaustubh for his great recommendations and help in making the project lift off.

About the reviewer

Neil Cuzon is a published technical writer who currently serves as a GitHub project maintainer and documentation owner for Mermaid.js. Neil has a passion for constant learning and the written word.

Despite having had a fruitful career as an equities and options trader, his heart always belonged to writing. That and his love for constant learning led him away from his career in finance and into the world of technical writing and software documentation.

You can contact him at [email protected].

Table of Contents

Preface

Section 1: Getting Started with Mermaid

Chapter 1: The Art of Documentation with Mermaid

Understanding the importance of documentation 

Clear definition of requirements and scope

Assisting in testing and maintenance

Better collaboration and teamwork

Increases the team's competencies

Preserve good procedures in the organizational memory

Documentation is important when working with agile development processes

Understanding Good, Bad, and Efficient documentation

What is bad documentation?

What is good documentation?

What is Efficient Documentation?

Guidelines for setting up Good Documentation

Archiving Documentation

Introducing Mermaid with Markdown

Blending Mermaid with Markdown

Blending text-based documentation with your code

Advantages of using Mermaid with Markdown

Summary

Chapter 2: How to Use Mermaid

Technical requirements

Adding Mermaid to a simple web page

Various Mermaid integrations (Editors, Wikis, CMS, and others etc.)

GitLab

Azure DevOps

WordPress

VuePress

MediaWiki

Remark

Pandoc

Mermaid Live Editor

Documentation with Markdown

What is Markdown?

Why use Markdown for documentation?

Quick Crash Course in Markdown

Setting up a simple custom documentation system using Docsify with Mermaid

Setting up your custom documentation system that supports Mermaid using Gatsby

Summary

Chapter 3: Mermaid Versions and Using the Live Editor

Technical requirements

Understanding Mermaid versions and the Release cycle

Semantic Versioning in Mermaid

The release cycle of Mermaid

Exploring the Mermaid Live Editor

How to access the Mermaid Live Editor

Functionality of Mermaid Live Editor

Rendering your first diagram using the Live Editor

Summary

Chapter 4: Modifying Configurations with or without Directives

Technical requirements

What are Directives? 

Using different types of Directives

The init directive

The wrap directive

Different configuration options

Top-level configuration options

Flowcharts

Sequence Diagrams

Gantt charts

User Journey diagrams

ER diagrams

Pie charts

State diagrams

Setting configuration options using initialize

Setting up the site configuration

Summary

Chapter 5: Changing Themes and Making Mermaid Look Good

Selecting a theme

Changing the theme for a whole site

Changing the theme for only one diagram

Different pre-built theme options for Mermaid

Customizing a theme using theme variables

Color theory

Selecting colors

Finalizing the new theme

Variables for modifying a theme

Summary

Section 2: The Most Popular Diagrams

Chapter 6: Using Flowcharts

Technical requirements

Getting started with flowcharts

Shapes and types of shapes

The rectangle shape

The diamond shape

The rounded rectangle shape

The stadium shape

The circle shape

The hexagon shape

The parallelogram shape

The alternate parallelogram

The asymmetric shape

The trapezoid shape

The alt trapezoid shape

The subroutine shape

The database shape

Configuring lines between nodes

Chaining

Types of edges

Thickness

Setting the length of an edge

Text on edges

Subgraphs

Setting a rendering direction in subgraphs

Special words and characters within labels

Interaction and styling

Interaction

Styling nodes and edges in your flowchart

Theming

mainBkg

nodeBorder

clusterBkg

clusterBorder

titleColor

lineColor

edgeLabelBackground

Summary

Chapter 7: Creating Sequence Diagrams

Technical requirements

Core elements in Sequence Diagram

Messages

Participants

Message types

Alt asynchronous messages

Semantics and common representation

Activations

Adding notes

Understanding Control Flows

Showing loops

Alternative flows

Displaying parallel flows

Exploring Additional features

Displaying Sequence Numbers

Using background highlighting

Adjusting the theme of sequence diagrams

actorBkg

actorBorder

actorTextColor

actorLineColor

signalColor

signalTextColor

labelBoxBkgColor

labelTextColor

labelBoxBorderColor

loopTextColor

activationBorderColor

activationBkgColor

sequenceNumberColor

Summary

Chapter 8: Rendering Class Diagrams

Technical requirements

Defining a class, members, and relationships

How is a Class represented?

Adding Members of a class

Support for additional information for members

Attaching relationships between classes

Labels and Cardinalities for Relationships

Adding Labels

Adding Cardinality

Using Annotations and comments

Adding Annotations

Adding Comments in Class Diagram code

Adding Interaction to Class Diagrams

Why add Interactivity to a class diagram?

Styling and Theming

Styling a specific class of a class diagram

Modifying class diagram-specific theme variables

Summary

Chapter 9: Illustrating Data with Pie Charts and Understanding Requirement Diagrams

Technical requirements

Rendering Pie Charts

Customizing pie charts

Understanding Requirement Diagrams

Defining Requirements

Defining Elements

Adding relationships in requirement diagrams

Customize theme variables for Requirement Diagrams

requirementTextColor

requirementBackground

requirementBorderColor and requirementBorderSize

relationLabelColor and relationLabelBackground

relationColor

Summary

Section 3: Powerful Diagrams for the Advanced User

Chapter 10: Demonstrating Connections Using Entity Relationship Diagrams

Technical requirements

Defining an Entity and its attributes

How is an Entity represented?

Adding the attributes of an Entity

Attaching Relationships between Entities

Customizing Theming Variables

Summary

Chapter 11: Representing System Behavior with State Diagrams

Technical requirements

Understanding states and transitions

Transitions between states

Choices

Composite states

Illustrating concurrency

Concurrency

Forks and joins

Adding notes and changing the direction of rendering

Direction of rendering

Theming

transitionColor

transitionLabelColor

labelBackgroundColor

stateLabelColor and stateBkg

compositeTitleBackground

compositeBackground

altBackground

stateBorder

specialStateColor and innerEndBackground

Summary

Chapter 12: Visualizing Your Project Schedule with Gantt Chart

Technical requirements

Creating a Gantt Chart with Mermaid

Understanding different elements of a Gantt Chart

Syntax for a Gantt Chart in Mermaid

Exploring Optional Parameters

Defining what an end date means in the Gantt chart

Advanced Configuration options and Comments

Configuration options for a Gantt Chart

Adding Comments in Gantt Chart code

Adding interactivity to a Gantt Chart

Why add interactivity to a Gantt Chart?

Attaching tasks to URLs

Attaching tasks to trigger JavaScript callback functions

Styling and Theming

Adding a Custom CSS style sheet

Modifying Gantt chart-specific theme variables

Summary

Chapter 13: Presenting User Behavior with User Journey Diagrams

Technical requirements

Defining a User Journey Diagram

How is a User Journey represented?

Basic syntax for a User journey diagram

Exploring Satisfaction Scores

Adding Actors to a User Journey diagram

Grouping the steps into sections

Styling and Theming

textColor

fillType (used for section/step group color)

actor

faceColor

Summary

Appendix :Configuration Options

Top-level configuration options

flowchart

sequence

gantt

journey

er

pie

state

Other Books You May Enjoy

Preface

This is a book about Mermaid, which lets you represent diagrams using text and code, simplifying the maintenance of complex diagrams.

Having the diagram in code simplifies maintenance and enables support by version control systems. In some cases, it is even possible to get refactoring support for name changes. It also facilitates simple collaboration within a team, where it is easy to distribute reviews and updates between team members. This ultimately saves you time and effort.

You will learn about Mermaid and put your knowledge to work with this practical guide to using Mermaid for documentation. The book takes a hands-on approach to implementation and associated methodologies that will have you up and running and productive in no time. The book can also serve as a reference for looking up the syntax for a particular diagram when authoring diagrams.

The book contains complete step-by-step explanations of essential concepts, practical examples, and practice exercises. You will begin by learning about Mermaid and documentation, before moving on to the general handling of Mermaid and finishing off with detailed descriptions of how to create the various diagrams supported by Mermaid.

With this book, you are first made familiar with efficient documentation and why it is important. Then, this book introduces Mermaid and establishes where it fits into the picture. Finally, you will learn how to use Mermaid syntax for various diagrams, using different tools and editors or a custom documentation platform. At the end, you will have enough confidence and knowledge to use Mermaid in your day-to-day work.

By the end of this book, you will know about the many different tools used to create Mermaid diagrams, and you will also have gained detailed knowledge about the different types of Mermaid diagrams, their configuration, and how they can be used in your workflows.

Who this book is for

Our target audience comprises a variety of content generators, such as technical writers, software developers, IT architects, business analysts, and managers – basically, professionals who are interested in documentation or the on-demand, easy, and fast representation of diagrams using simple text code snippets, with the ability to extract them.

This will be a definitive guide that assumes you have little to no knowledge of what Mermaid is or how to use it. Any familiarity with documentation using Markdown will be helpful, but is not a necessity.

What this book covers

Chapter 1, The Art of Documentation with Mermaid, contains an introduction to Mermaid, ideas about effective documentation, why Mermaid came into being, and why you should use Mermaid for documentation.

Chapter 2, How to Use Mermaid, is where you can read about how to get started with Mermaid. You will see different ways in which Mermaid can be used and applied. Usages can vary from adding Mermaid to your website to using tools and editor plugins that already have Mermaid integrated and adopted. The chapter also covers working with documentation using Markdown and how to set up your own custom Mermaid-powered documentation system.

Chapter 3, Mermaid Versions and Using the Live Editor, explains Mermaid versioning strategies, which versions should be used, and what to expect from future versions. You will look at the Mermaid Live Editor, its different features, and how to render your first diagram using the live editor.

Chapter 4, Modifying Configurations with or without Directives, describes directives, which are a way of modifying the configurations for a diagram using code. It explains the possibilities of directives and what can be achieved by applying directives to diagrams. The chapter continues by detailing the different configuration options that Mermaid supports. Finally, the chapter describes the different ways in which configurations can be applied when integrating Mermaid with a website.

Chapter 5, Changing Themes and Making Mermaid Look Good, describes how to change the theme for Mermaid diagrams, both using directives and via the initialize call. The chapter describes the pre-made themes available as well as how to create a custom theme using the dynamic theming engine in Mermaid. The chapter describes the general theming functionality and the common theme variables that can be overridden.

Chapter 6, Using Flowcharts, focuses on creating flowcharts using Mermaid. It covers the layout and orientation of the flowchart, how to define different types of nodes, and creating edges between nodes. It highlights how you can draw sub-graphs within a graph. It teaches you how to add interactivity to your diagram by binding clicks to callback functions or to URLs. It includes many practical examples covering different aspects of flowcharts, such as different configurations and theming variable overrides. It also contains practical exercises to increase your understanding.

Chapter 7, Creating Sequence Diagrams, describes sequence diagrams, which show events between objects or participants in a specific order, or sequence. It explains how to define participants and aliases as well as how to define messages. It also explains how to mark a message as active. The chapter also describes how to add notes in sequence diagrams and various control flows. The control flows can be loops, if statements using the alt mechanism, and parallel flows. The chapter will teach you how to turn sequence numbering on and off and how to highlight a specific part of the diagram using the background highlighting mechanism.

Chapter 8, Rendering Class Diagrams, focuses on the most widely used diagram in the object-oriented programming paradigm, that is, the class diagram. It focuses on how to render different elements of a class diagram, such as classes, its member variables, and functions. It shows how Mermaid supports adding different relations among classes, and attaching, different cardinalities. It also covers how to add different annotations, such as declaring a class as an interface or abstract to highlight its importance in the diagram. You also learn how to add interactivity with support for click events and callbacks.

Chapter 9, Illustrating Data with Pie Charts and Understanding Requirement Diagrams, covers the pie chart, which is one of the simplest diagrams to draw using Mermaid. It focuses on the general syntax of a pie chart and title, as well as looking at the given dataset. It also teaches you about adjusting theme variables to change the color scheme and other configuration settings. The chapter also covers requirement diagrams, which are specified using UML 2.0. The chapter describes how to create requirement entries, define attributes, and create relationships between different entries.

Chapter 10, Demonstrating Connections Using Entity Relationship Diagrams, looks at entity relationship (ER) diagrams. An ER diagram shows how entities are connected in a specific domain and how relations are established between them. This chapter describes the general syntax of ER diagrams in Mermaid. It also shows how identification is handled as well as how to define attributes on entities.

Chapter 11, Representing System Behavior with State Diagrams, describes state diagrams, which are often used in computer science to illustrate the behavior of systems. It covers the syntax and usages of core elements of state diagrams, such as states starting, ending, and transitioning from one state to another, and it teaches you how to define the entire flow of transitions. It explains the complexities of composite states, the usage of forks, and concurrency concepts.

Chapter 12, Visualizing Your Project Schedule with Gantt Chart, covers Gantt charts. Gantt charts illustrate project plans by representing tasks as horizontal bars where the x axis represents the timeline. This chapter describes how to create Gantt charts using Mermaid and how to set the input and output date formats. It also describes the handling of the today marker and how to set up interaction in diagrams by binding clicks to callback functions or to URLs.

Chapter 13, Presenting User Behavior with User Journey Diagrams, focuses on user journey diagrams, which are extremely useful for business analysts, UX designers, and product owners. The diagram shows the user's experience as a series of steps, where the user's satisfaction score is highlighted for each step. The diagram can represent a user's journey while visiting a website or during some other tasks. You will learn the syntax of how to define a user journey, breaking it down into different individual sections and a series of steps to complete those sections by the different actors involved.

To get the most out of this book

Start by reading the first section, which describes the basic concepts and common features for all diagram types. After that, you can read the diagram-specific chapters in any order.

For most of the examples in the book, you only need an editor with support for Mermaid. A good editor that is easy to access is Mermaid Live Editor, which can be found online (https://mermaid-js.github.io/mermaid-live-editor/) and only requires your browser to run.

Apart from that, some sections may require a rudimentary knowledge of HTML, such as what an element is and what CSS is.

In order to run the examples on setting up documentation systems, you will need a JavaScript interpreter called Node.js, which runs from the command line. It needs to be installed on your machine. If you do not already have Node.js installed, you can download it from https://nodejs.org/en/, which contains the installation options and appropriate instructions.

If you are using the digital version of this book, we advise you to type the code yourself or access the code via the GitHub repository (link available in the next section). Doing so will help you avoid any potential errors related to the copying and pasting of code.

If you find errors in the Mermaid library, please submit an issue to the Mermaid GitHub repository at https://github.com/mermaid-js/mermaid.

Download the example code files

You can download the example code files for this book from GitHub at https://github.com/PacktPublishing/The-Official-Guide-to-Mermaid.js. In case there's an update to the code, it will be updated on the existing GitHub repository.

We also have other code bundles from our rich catalog of books and videos available at https://github.com/PacktPublishing/. Check them out!

Download the color images

We also provide a PDF file that has color images of the screenshots/diagrams used in this book. You can download it here: https://static.packt-cdn.com/downloads/9781801078023_ColorImages.pdf.

Conventions used

There are a number of text conventions used throughout this book.

Code in text: Indicates code words in text, database table names, folder names, filenames, file extensions, pathnames, dummy URLs, user input, and Twitter handles. Here is an example: "When you add a subgraph, you start with the subgraph keyword followed by the subgraph ID."

A block of code is set as follows:

flowchart LR

  subgraph Dolor

    Lorem --> Ipsum

  end

When we wish to draw your attention to a particular part of a code block, the relevant lines or items are set in bold:

flowchart LR

      Lorem --> Ipsum

      click Lorem "http://www.google.com" "tooltop" _self

Any command-line input or output is written as follows:

$ npm install -g gatsby-cli

Bold: Indicates a new term, an important word, or words that you see on screen. For example, words in menus or dialog boxes appear in the text like this. Here is an example: "The quotes also make it possible to use keywords such as flowchart and end in the label text."

Tips or important notes

Appear like this.

Get in touch

Feedback from our readers is always welcome.

General feedback: If you have questions about any aspect of this book, mention the book title in the subject of your message and email us at [email protected].

Errata: Although we have taken every care to ensure the accuracy of our content, mistakes do happen. If you have found a mistake in this book, we would be grateful if you would report this to us. Please visit www.packtpub.com/support/errata, selecting your book, clicking on the Errata Submission Form link, and entering the details.

Piracy: If you come across any illegal copies of our works in any form on the internet, we would be grateful if you would provide us with the location address or website name. Please contact us at [email protected] with a link to the material.

If you are interested in becoming an author: If there is a topic that you have expertise in and you are interested in either writing or contributing to a book, please visit authors.packtpub.com.

Section 1: Getting Started with Mermaid

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

This section comprises the following chapters:

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

Chapter 1: The Art of Documentation with Mermaid

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

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

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

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

In this chapter, we will cover the following topics:

Understanding the importance of documentationUnderstanding the difference between Good and Bad documentationIntroducing 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

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.