User journeys: sections, tasks, actors

简介 / Introduction

Journey diagrams visualize the steps different actors complete across phases of a process. Both PlantUML and Mermaid support this diagram type, but their syntax differs significantly. This post对比同一示例的两种写法。

PlantUML 版

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultFontSize 13

title User Order Flow

scope Start as "Start"
scope Order as "Order"
scope Payment as "Payment"

|role: Customer|
:Browse products; #LightBlue
:Add to cart; #LightBlue
|#Order|
:Confirm order; #Gold
:Submit order; #Gold
|#Payment|
:Select payment method; #LightGreen
:Complete payment; #LightGreen

|role: Merchant|
|#Order|
:Receive new order notification; #Gold
|#Payment|
:Confirm payment received; #LightGreen

|#Order|
note right: Merchant receives order simultaneously

@enduml

PlantUML uses |<Role>| to declare actors, |#Stage| to group tasks, and supports the scope keyword for parallel regions. Tasks are written as :description;.

Mermaid 版

1
2
3
4
5
6
7
8
9
10
11
12

journey
    title User Order Flow
    section Order
        Browse products: 5: Customer
        Add to cart: 4: Customer
        Confirm order: 3: Customer
        Submit order: 2: Customer
        Receive new order notification: 3: Merchant
    section Payment
        Select payment method: 5: Customer
        Complete payment: 4: Customer
        Confirm payment received: 5: Merchant

Mermaid’s journey diagram uses section to define stages; each task line follows task: score: actor. The score (1-5) indicates the step’s importance to the user. Mermaid does not require explicit actor declarations — the actor name appears on each task line.

对比 / Side-by-side

小结 / Wrap-up

PlantUML journey diagrams suit multi-actor, multi-stage parallel scenarios — verbose but powerful. Mermaid journeys are concise and ideal for lightweight docs and blog embeds. The core difference lies in how stages and actors are declared; choose based on whether you need colors or parallel regions.