User Journey Diagrams

What are User Journey Diagrams?

Mermaid's User Journey Diagrams are a visual representation of the steps users take to complete a task within a system, application, or website. These diagrams illustrate the current ("as-is") user workflow, helping identify bottlenecks and areas for improvement in the future ("to-be") workflow.

Mermaid provides the ability to render User Journey Diagrams using simple text-based syntax. These diagrams are useful for analyzing and improving user experience.

---

Creating Your First User Journey Diagram

1. From the Code IDE, click Apps and Agents in the left-hand panel.

2. Select Mermaid. Paradime will automatically start a new Mermaid project.

3. In the terminal, use the arrow keys to select "User Journey Diagrams."

4. A new UserJourney.mmd file will be created in your editor with this starter template:

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

1. Click the eye icon (👁️) in the top-right corner of your Mermaid file to preview the diagram.

2. Edit and update your .mmd file as needed—the preview will update automatically.

---

Diagram Syntax Guide

Basic Structure

A User Journey Diagram consists of the following components:

• Title: Describes the overall user journey.

• Sections: Break down the journey into major steps or phases.

• Tasks: Individual actions within a section.

The basic syntax is as follows:

journey
    title Journey Title
    section Section Title
      Task Name: Score: Actor(s)

Defining Tasks

Each task is defined with:

• Task Name: A descriptive label for the task.

• Score: A number from 1 (negative experience) to 5 (positive experience).

• Actors: The individuals or entities involved in the task, separated by commas.

Example:

journey
    title Example User Journey
    section Example Section
      Task 1: 4: User
      Task 2: 2: User, System

Defining Sections

Sections group related tasks together and are defined using the section keyword followed by the section title.

Example:

journey
    title Product Purchase Journey
    section Browsing
      View product: 5: User
      Search for alternatives: 4: User
    section Purchase
      Add to cart: 5: User
      Complete payment: 3: User, Payment Gateway

---

Examples

E-Commerce Purchase Journey

journey
    title E-Commerce Purchase Journey
    section Browsing
      Explore homepage: 4: User
      Search for products: 3: User
      View product details: 5: User
    section Checkout
      Add to cart: 5: User
      Apply coupon: 3: User
      Make payment: 4: User, Payment Gateway
    section Post-Purchase
      Receive confirmation: 5: User
      Provide feedback: 4: User

Software Installation Journey

journey
    title Software Installation Journey
    section Download
      Visit website: 4: User
      Select download link: 5: User
    section Installation
      Open installer: 3: User
      Complete setup: 4: User, Installer
    section First Use
      Launch software: 5: User
      Complete onboarding: 3: User, Support Bot

---

Best Practices

1. Keep it Simple: Use clear task names and group related tasks into sections.

2. Use Scores Effectively: Assign scores based on user experience (1 = poor, 5 = excellent).

3. Include Relevant Actors: Specify all participants involved in each task.

4. Iterate: Refine the diagram as new insights are gained about the user journey.

5. Focus on the User: Highlight pain points and positive moments in the journey.

---

Additional Resources

For more syntax options and advanced features, visit the official Mermaid documentation.