User Journey Maps are an interesting diagram in product development that I'm starting to see more and more. These diagrams, like the one pictured below, allow you to visualize the entire flow of a user trying to accomplish a task.

In this article, we'll explore how to easily create User Journey Maps using markdown and Mermaid.js.

What are User Journey Maps?

The key benefit of User Journey Maps is that they allow you to see the things that are contributing to a positive experience as well as a negative experience.

User Journey Maps do this by plotting each part of a user's experience as a story from the left to the right. The user's satisfaction level with each leg of their journey is usually depicted in the vertical axis along with a helpful emoji indicating how pleased the user is.

The end result of a user journey map is that you can quickly visualize the strong and weak areas of your products and services and make targeted improvements to improve the overall experience.

In this article, we'll explore how to create user journey map diagrams in markdown using Mermaid.js.

What is Mermaid.js?

Mermaid.js is an open-source diagramming library in JavaScript that takes specialized markdown and "automagically" converts it into a working diagram.

There are many different diagrams that are supported by Mermaid.js includingentity relationship diagrams,sequence diagrams,class diagrams, and evengit graphs.

Mermaid.js is supported in a variety of tools and services including GitHub markdown,Polyglot Notebooks, a Visual Studio extension, and a live online editor. Mermaid.js can also be manually included in any website you create.

Basic User Journey Maps in Mermaid.js

At its most basic level, a user journey map with Mermaid.js starts with ajourney node, followed by a list of tasks, a colon, and the user's satisfaction level.

Mermaid.js works best if you provide a 0 for your lowest level of satisfaction and up to a 7 for your highest level of satisfaction.

Here is a user journey map describing the experience of attending a fictional tech conference:

journey    title Attend a Tech Conference    Buy a Ticket: 4    Check Schedule before Conference: 6    Check in at Conference: 5    Check Schedule at Conference: 4    Attend Talk: 5    Lunch: 3    "Hallway Track": 5    Post-Conference Movie: 7

In this hypothetical example, the low points of the experience were purchasing tickets and lunch, while the high points involved the movie, sessions, and schedule experience.

Adding Sections to a User Journey Map with Mermaid.js

Sometimes your user journey involves distinct phases that can be helpful to highlight. For example, if a user transitions from one team or area of your product to another, representing this on the map can be very helpful.

In Mermaid.js, we can addsection nodes to the markdown to group individual tasks into these sections as shown below:

journey    title Attend a Tech Conference    section Pre-Conference        Buy a Ticket: 4        Check Schedule before Conference: 6    section Morning        Check in at Conference: 5        Check Schedule at Conference: 4        Attend Talk: 5    section Afternoon        Lunch: 3        "Hallway Track": 5        Post-Conference Movie: 7

This can help highlight the highs and lows of various segments of a user's journey as well as entire sections that might be below par.

Adding Participants to a User Journey Map with Mermaid.js

Finally, Mermaid.js user journey maps allow us to indicate theparticipants in each task. This can help you identify factors for good and bad user experiences across all legs of the user journey.

Participants can optionally be named for each task by adding a: following each score and then a comma-separated list of participants. Mermaid.js will then automatically assign each participant a color and include them in the legend.

journey    title Attend a Tech Conference    section Pre-Conference        Buy a Ticket: 4: Attendees, Point of Sales        Check Schedule before Conference: 6: Attendees, Web Site    section Morning        Check in at Conference: 5: Attendees, Volunteers        Check Schedule at Conference: 4: Attendees, Mobile App            Attend Talk: 5: Attendees, Speakers, Volunteers    section Afternoon        Lunch: 3: Attendees, Volunteers        "Hallway Track": 5: Attendees, Volunteers        Post-Conference Movie: 7: Attendees, Volunteers, Speakers

In this particular example, I don't see any strong indicators of good or poor performance based on the participants. However, participants can be helpful in identifying unusual trends as well as simply communicating who is involved in each leg of the journey to various stakeholders.

Closing Thoughts

I personally haven't used user journey maps much through my career, but I see a lot of potential for them.

User journey maps can help:

• Highlight strong and weak areas
• Map the user's experience from start to finish
• Identify key participants in the journey
• Find correlations between participants and strong and weak areas

I plan on using user journey maps significantly more in the future, and the ease of using Mermaid.js to create effective visualizations is one key reason why.