How to Communicate Your Process Visually using BPMN as Code
Tags: diagram, team, productivity, engineering
Published: 2023-01-23 17:50:41

_When you have multiple participants in a process, and we often do, you realize that you're dealing with a lot of miscommunication / misalignment issues. It's so hard to remember who was doing what and when, furthermore it's even harder to make some optimization in the process itself as you lose the control over it.  Besides you'll need to group all the participants together for them tell their opinions._

Processes are long and complex, but they're there even if you don't formalize them. So, why don't we find a way to approach it in an easy way? First thing each of us would do in such a situation is drawing some boxes and lines, a.k.a. diagrams. Today, we're going to talk about ways of drawing some diagrams, in a comprehensive yet simple way.

## Business Process Model and Notation (BPMN)

BPMN diagram is like [Flowchart](https://en.wikipedia.org/wiki/Flowchart), but the tasks (activities) are grouped by the participants. It can be drawn / read by both business or technical people as the main purpose is to **communicate a process in a simple yet complete way**.

![Simple BPMN diagram for pizza ordering](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bqidzymuw6tjs88k0ozk.png)

BPMN is actually a [set of standards](https://www.bpmn.org/) has been used for years for complex enterprise processes, and nowadays it's becoming more accessible thanks to the development of the new techniques. Web based tooling (like [Camunda](https://camunda.com/), [BPMN.io](http://bpmn.io/)), more [platforms supporting integrating diagrams into the flows](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/), and remote work culture all helps us to use BPMN easier. Besides all of that, we drive/lead more and more initiatives together and we're keep looking for the efficiency and improvement.

I started to see more and more teams are formalizing their development / pull request flows. Many of them are going with a very long, not up-to-date flowchart diagrams just to keep the things "simple" and not require learning any better suited specifications like BPMN. It's a fair tradeoff, but at the end, it makes these diagrams not serving to their purposes. We should rather prefer solutions that makes BPMN diagrams more friendly, and super easy to learn/draw.

## Diagram as Code

Diagram as Code is a trending concept that automatically generates diagrams from a simple text/code. Some of the pioneers are [PlantUML](https://plantuml.com/), [Mermaid](https://mermaid.js.org/) and [Kroki](https://kroki.io/). It has several great benefits like having your architecture diagrams close to your code and your development flow. If you want to learn more about it, there's a [presentation](https://www.slideshare.net/sakirtemel/diagrams-as-code) that covers main benefits in action.

![Visualization of Diagram as Code with PlantUML](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/vcjpmqjnrvgkdu8ron3k.png)

## BPMN as Code with BPMN Sketch Miner

[BPMN Sketch Miner](https://www.bpmn-sketch-miner.ai/) is a rapid sketching tool for BPMN process models, you just write it as you're telling a story. They also have a great BPMN tutorial to make understanding of BPMN easier.

![Simple BPMN diagram for pizza ordering with using BPMN Sketch Miner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/8xd9cb1hnr37crwm06b4.png)

_Waiter, Chef, Customer are the **roles** defined as [Lanes](https://www.bpmn-sketch-miner.ai/doc/02-pools.html#pool-task-annotation), the yellow rectangles are [Tasks](https://www.bpmn-sketch-miner.ai/doc/01-tasks.html), the circles are [Events](https://www.bpmn-sketch-miner.ai/doc/04-events.html#start-and-end-events), the arrows are the [Flows](https://www.bpmn-sketch-miner.ai/doc/05-message-flow.html)._

Since we learnt the basics, we can **just start** drawing of one of our processes **!** Sounds a bit strange, right? BPMN as a set of standards seems complex to learn because it has [hundreds of elements](https://www.bpmn.org/) that allows us to map almost any situation in the real world, but do we need all of them to start? To me, it's very similar to when we learn programming languages, you don't need to know / apply the best of the bests to be able to create an application, you know that you can continuously improve your codebase later on. Since now we're **storing our diagrams as code in our codebases**, the same rule applies! Just start mapping a process that you believe it can be helpful for your team to have it visualized.

### Using more features of BPMN

Here you can see how you can evolve the diagram above by using a few more elements of BPMN.

![Evolved BPMN diagram for pizza ordering with using BPMN Sketch Miner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/kt83uoqghhvbekdmyuzb.png)

_[Start and End events](https://www.bpmn-sketch-miner.ai/doc/04-events.html#start-and-end-events) are **labeled**, used [Timer event](https://www.bpmn-sketch-miner.ai/doc/04-events.html#timer) to represent delay, [Exclusive Gateway](https://www.bpmn-sketch-miner.ai/doc/03-gateways.html#exclusive-gateways) is used to **branch** for **alternative paths**, Loop is used for repeated actions._

Another great thing I use in BPMN is the [Data and Message Flow](https://www.bpmn-sketch-miner.ai/doc/06-data.html#data-flow), it clearly describes who needs what and when, and where it's generated at. This is one of the biggest ambiguity in the processes and often it's missed because of the assumptions. BPMN helps us to explicitly talk about that.

![BPMN diagram for job application process using BPMN Sketch Miner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/e3bv3fx7wmp8hglr0kha.png)

_[Message Events](https://www.bpmn-sketch-miner.ai/doc/04-events.html#message) are used to represent what's **received or sent** with the tasks, [Data objects](https://www.bpmn-sketch-miner.ai/doc/06-data.html) used to show inputs and outputs of the tasks. [Data Flow](https://www.bpmn-sketch-miner.ai/doc/06-data.html#data-flow) is used to describe how the data is processed throughout the process._

### Mapping our processes

Imagine you'd like to describe what's [the journey of your feature](https://www.bpmn-sketch-miner.ai/examples/demos-10-16-appstore.html) from being developed to customers using that. You may want this to cooperate with marketing department for them to understand better which steps are there and they can align, you can use it for your new team members to onboard them faster, or you can use it for a brainstorming session with different experts to see if there's a way to optimize the process. Either way, just start drafting something and live-edit it during your meeting.

![BPMN diagram for application publishing process with using BPMN Sketch Miner](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/thp75640c4te4qyr5ntu.png)

### BPMN Sketch Miner VSCode Extension

There's a [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=s-v-o.bpmn-sketch-miner) to integrate BPMN Sketch Miner to your development flow easily. I often store them under _docs/diagrams/source/process_name.sketchminer_ and the png versions at _docs/diagrams/out/process_name.png_.

![BPMN Sketch Miner VSCode Extension](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/bnv7b6a46lcgty2lde7q.png)

## Further thoughts

Visually expressing our thoughts or new processes engages people more and allows going more efficient in our discussions. [BPMN](https://www.bpmn.org/) is the language of the processes and it's good to speak this language, and even daily basis. This article covered how to start doing that, of course there'll be a lot of development opportunities on the go, a few of them are; how to use it in our git flow, using BPMN files as an outcome to auto generate forms etc, allowing teams to describe their internal or external facing processes in an efficient manner. Note that the diagrams help with having shorter and interesting meetings, async work, less regression of the established practices, and less resistance of a change. Feel free to [contact us](https://www.kelebeklabs.com/contact) if you encounter any of the opportunities, always happy to share our practices.