Why not document zeebe itself using BPMN?


I read through all available documentation. I found few attempts to explain various state transitions in different diagram styles:

Have you considered to try to explain how zeebe works using BPMN itself? I think it is safe to assume that anybody who is interested in this tool is able to read BPMN. This way you could prove that you can explain how your system works using the very tool you promote for others to use.

What do you think? :slight_smile:


Hi @akrakra,

Thanks for sharing your idea. Using BPMN to document the behavior of state machines is certainly possible. I’m not sure if it is a good a idea to do so in the Zeebe docs, though, for these reasons:

  • Zeebe is also targeted at people who are new to BPMN. We would like them to learn BPMN along as they learn Zeebe. They may not yet understand BPMN when they read about the basics of the system or could confuse those BPMN models with those that Zeebe executes.
  • While BPMN can be used to document state machines, it is not a formal language to do so (e.g. a sequence flow label is not formally a transition condition). It may therefore be better to use a notation that is entirely informal and that users can clearly identify as informal.

I hope you enjoy reading the docs nevertheless. Please provide us with any more feedback that you may have. There is still a lot of room for improvement :slight_smile: