Mapping User Journeys with Mermaid.js

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 including entity relationship diagrams, sequence diagrams, class diagrams, and even git 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 a journey 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 add section 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 the participants 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.