Readability Matters

17 April 2024 Haarsteeg 1696 words, 5 minutes #tech  #bpmn  #camunda  TL;DR

We use process models to document the control flow of a process. Those models can even be executed by software if you take the effort. I love these models and I see a lot of them. My sense is they could be better and not just in the generic "everything can be improved" way. Very specifically, our models could become better if their readability were improved. Because readability matters.

Process models become so much better when you pay attention to how easy they are to read. Similar to source code for software, we end up reading them more often than creating and changing them.

Many models look like we put the elements together and then moved on. Sure, they work, but do they work as well as they might? I don’t think so. Most suggestions in this area are quite simple, and they’re useful as guidelines in most cases (not all), but as with many things, it’s easy to explain, hard to master. What makes for a readable model?

BPMN

The Set Up

You may be looking at your own work, but also others. Remember that e-mail from last month? Nope. Remember those detailed notes you took and plan you outlined last month? Nope.

Imagine not having been the author. Process models are important in communicati09on, in communicating intent.

There’s research, but I’ll stick to things that ring true from practical experience Because readability matters. For you, and for us all.

Some Suggestions

If anything, Be consistent. It’s not uncommon to see big differences depending on the author(s), the time available, the season, etc.

Needs to feel like coming home.

Left to right, communication tool

Alternatives break from line.

Name activities, events, some of the gateways and use good conventions to convey meaning: no activities for events!

ASligning things and applying symmetry and visual balance

Use some space

Know your language - ref other posts (raffle and linkedin)

Don’t pollute with technical details Don’t overuse data elements Do add text annotations for multi-instances

Example diagrams

Camunda’s Readable diagrams Course

  • Guidelines provide a framework and orientation to create clear, effective models

  • Labelling elements will consistently inform the reader of the business semantics

  • Naming conventions provide consistency, clarity and effective communication

  • Modelling symmetrically from left to right makes BPMN diagrams more intuitive and easier to understand.

Do’s and Don’ts

You can sketch, then clean up later

Link up linking elements - messages, errors, signals and links

Process ended doesn’t help as an end event name. You want to find those end states, particularly when analysing the data. Good names are everything and is hard, but worth it!

(Use colours when discussing?)

From Trainings

  • Don’t merge exclusive end states - contrary to 7pmg, but it is useful to know in which state we completed. Same goes for parallel

  • Don’t use conditional flow from an activity to model exclusive paths - use the gateway instead

  • There is no need to merge immediately before a single end event for the process

    • Separate end events represent the different possible outcomes

  • Activities are named VERB-NOUN (imperative form, e.g. Act on Object)

  • Processes are named VERB-NOUN as well: Approve Request

  • Avoid using technical terms such as "Store Document" or "Read Account"

  • Describe what should happen, not how it happens

  • Name of a diverging exclusive gateway is a question

    • Name represents the decision evaluated

    • Names of outgoing sequence flows from the gateway are answers to that question

  • Exclusive gateways receive exclusive conditions where possible

  • Don’t name parallel gateways

    • There is no decision or any process-specific semantics to its use

  • Events are named NOUN-VERB (past tense)

    • Examples: Customer Registered, Retention Period Expired

  • Name describes what has happened to trigger the event, e.g. Order Rejected

  • For timer events, indicating the period or moment is usually better

  • Do not overuse: a regular end event is just as strong as a terminate

Text Annotations

  • Use tactically to provide relevant information

    • Example: multi-instance markers: add the collection description in a text annotation

Pools and Lanes

  • Label the pool for the process

  • Unpopular opinion: don’t use pools and lanes from level 2 onwards

    • They convolute the diagram (lots of vertical movement)

    • The process flow is broken

    • Automated activities & events have no obvious lane to go into (and a separate "system" lane makes the previous problems even worse)

Data Objects and Data Storage

  • Don’t litter the diagram with every piece of data

    • Include the ones that aren’t obvious or help to understand the flow or collaboration

  • Conditional events: name signifies the condition monitored

  • Link events, Signal events, Escalation events: labels of corresponding throw and catch should match

  • Business rule tasks

    • Consider a business rule task even when not using a DMN model

Gateways

  • Consider event-based gateway vs. receive task with boundary events

  • Don’t use names for event-based gateways and converging inclusive gateways: the behaviour is never process specific

  • For diverging inclusive gateway, consider naming as a question with answers on outgoing sequence flows, just like exclusive gateways

  • A business rule task is a natural predecessor to a diverging inclusive gateway

  • Don’t add conditions to sequence flows leaving an event-based gateway

Iteration

  • Always use a text annotation near the iteration marker to indicate the condition or collection

  • Consider using a separate process model for the contents of a multi-instance body because the objects you operate on don’t match 1:1

  • Multi-instance pools make most sense as part of a collaboration of pools because the relationship with the "parent" is visible

  • With interrupting boundary events, all instances will be aborted

  • With throw - catch: place boundary event close if possible

  • When using pairs and/or sets of throwing and catching events, use the same labels for visual linkage

    • Even more important when there are multiple sets in a model

Using Signals

  • Consider signal events only when message events, escalation events and error events don’t suffice

    • Messages communicate with other pools

    • Errors and escalations can only throw to the boundary of their parent

  • Use signal events when you need these characteristics:

    • Communication / synchronisation between parallel branches inside a process

    • Broadcast (publish/subscribe) between processes

    • Throw and continue normally (as opposed to error events and terminate events)

Errors

  • Be deliberate when applying errors: rely on default behaviour for other situations

  • Did the activity complete normally? Errors imply interruption

  • Consider error end event for a process, even if not catching

Transactions?

  • Don’t apply transaction subprocesses everywhere

    • Most useful for coordinated and/or automated compensation

  • Consider process scope when applying compensation

    • Don’t expand the scope just to benefit from compensation features

    • The goals is not to capture entire life cycles in as few process models as possible

Event Subprocesses?

  • Use event subprocess to prevent repeated boundary events

  • Use compensation start event for event subprocess if compensations are not 1:1 with activities

Look into Rutger van Dijk’s ideas: https://www.mycubes.nl/downloads/mycubes-bpmn-guidelines.pdf Line things up Steps to systems: keep the names generic in the process model.

Does it really matter?

Getting it to work is not good enough.

When we have an issue, we need to understand WHY it’s handled in a certain way

If how you describe how you work is a mess, your work is more likely to be a mess too, because apparently you don’t care

Clean up is not that much work

raffle base model
Figure 1. Base Model for the Raffle
round half up((random number() * Number_of_Participants * Votes_per_Participant),0)