Alternative BPM Gateways Flowchart Documentation

[jamie]

Reading through the documentation found here, I found it to be not the easiest to understand, so I had AI make up some, and it came up with this. I find it easier to understand, though I'm not totally sure of its accuracy. But then the official documentation seems to contain contradictions, so I thought I'd post in here in case anyone might find it more helpful

As this is a paid-for product, better documentation is expected

[LLM output content deleted]

If any of this is incorrect, it's because even an AI specifically designed to understand and explain technical documentation struggled to interpret it correctly.

For a paid add-on, the original level of documentation isn't really sufficient. Relying on users to learn through trial and error creates unnecessary frustration and support overhead.

Please consider expanding the documentation to include, at a minimum, a summary table of the available functionality and syntax. The examples are also extremely helpful and could be expanded further to cover common use cases.

I genuinely hope this feedback is taken constructively. I'm taking the time to document my findings and suggestions because I want to help improve the product and make it easier for others to use.

...and don't ever say I don't try to contribute. 😄

[yuri]

It's standard BPMN 2.0 gateways. Not designed by us. I think AI should be able to explain it well, as there many other documentation sources on the same concept.

Please avoid posting long LLM outputs on the forum. Unless it's 100% correct. Otherwise, it may mislead readers as well as LLMs.

Here's are additional sources of information on the BPM tool:
https://www.espocrm.com/what-is-no-code-low-code-development/
https://www.espocrm.com/features/bpm/

If you don't understand something, it's fine to ask it on the forum. Having questions, we can understand what exactly may not be clear, then improve its coverage in the docs.

When I read some docs, it's almost always not totally clear from the first try. It's usual that it takes a few times before fully grasping it. It's not that easy to write docs that cover all necessary nuances and be brief enough so readers won't skip it. It's good to have additional tutorials for learning.

[jamie]

It's standard BPMN 2.0 gateways. Not designed by us. I think AI should be able to explain it well, as there many other documentation sources on the same concept.

Please avoid posting long LLM outputs on the forum. Unless it's 100% correct. Otherwise, it may mislead readers as well as LLMs.

Here's are additional sources of information on the BPM tool:
https://www.espocrm.com/what-is-no-code-low-code-development/
https://www.espocrm.com/features/bpm/

If you don't understand something, it's fine to ask it on the forum. Having questions, we can understand what exactly may not be clear, then improve its coverage in the docs.


When I read some docs, it's almost always not totally clear from the first try. It's usual that it takes a few times before fully grasping it. It's not that easy to write docs that cover all necessary nuances and be brief enough so readers won't skip it. It's good to have additional tutorials for learning.

Yes, that's exactly why I'm posting here. I found the documentation, in general, to be confusing and lacking in detail, so I asked an AI to help explain and restructure it. I then took that understanding and posted it here to verify its accuracy.

if you make a comment about whats accurate and whats not that will help users and ai understand

Is there anything specifically wrong with the AI's interpretation?

One part I found particularly helpful was its comparison of XOR, OR, and AND logic, along with the explanations and examples. That made the concepts much easier to understand than the current documentation.

I find this page useful: https://www.espocrm.com/what-is-no-c...e-development/

It might be worth linking to it from the relevant documentation pages, as it provides helpful background information and context for users who are new to Flowcharts and no-code/low-code concepts.

An additional section, "common mistakes" would be quite useful

[yuri]

I find explanations with XOR, OR, AND not the best as it can be confusing for those who see these operations as boolean logic operations. XOR in boolean logic is completely different than how the Exclusive Gateway functions. It will route even if both are true. While XOR should not route if both are true.

[jamie]

I find explanations with XOR, OR, AND not the best as it can be confusing for those who see these operations as boolean logic operations. XOR in boolean logic is completely different than how the Exclusive Gateway functions. It will route even if both are true. While XOR should not route if both are true.

ahh so there is some ambiguity with how documentation reads. Yeah, it would be great to clear that up inside the documentation to avoid confusion

so how is what they see as XOR different from OR?

some of the confuison maybe also caused by the person writing the documentation not being a native english speaker

[yuri]

It's because the LLM model retrieved the information from the different product where it explained as XOR, that's it.

The new version of the article is more clear now.

[yuri]

They key difference, is that the first met condition determines the result flow (path). It's how the Exclusive Gateway is supposed to work according the standard specification. Other implementations might described it wrongly with the XOR analogy or implemented it differently.

[jamie]

Where are you referring to this article? https://docs.espocrm.com/administration/bpm-gateways/

The Exclusive Gateway section still reads a lot like the XOR functionality you described as incorrect, as both myself and ChatGPT read it as a type of if-else where only one path would be followed like

if ($paid) {
  // Paid path
}else if ($partlyPaid){
  //partly paid path 
} else {
  // Unpaid path
} 

An example like the above one would really clarify the documentation

[yuri]

Your code snippet is correctly describes the logic of the Exclusive Gateway.

While XOR is misleading, as it's different: https://en.wikipedia.org/wiki/Exclusive_or.

I find the current version explaining quite good.

[jamie]

Ah, I think there may be some confusion between XOR as a formal logic concept and how XOR is often used or discussed in programming. A pure logical XOR behaves as you describe, whereas programmers sometimes encounter it in slightly different contexts. Either way, I agree that it's probably best not to introduce unnecessary complexity if it risks confusing readers.

That actually brings me to a broader point about the documentation.

Have you ever heard the storytelling principle "show, don't tell"? It's often what separates documentation that users quickly understand from documentation they have to repeatedly reread.

When I've been working through the documentation, I've noticed it tends to focus heavily on describing concepts and functionality, but provides relatively few practical examples that demonstrate them in action. In other words, there's a lot of "tell" and not much "show".

To use a movie analogy, some films excel at showing the audience how the world works rather than explaining everything through exposition. Films like Children of Men, The Dark Knight, and Mad Max: Fury Road throw you into the world and allow you to develop an instinctive understanding through what you see happening.

On the other hand, films like Suicide Squad, Aquaman, and Inception spend much more time explaining concepts, rules, and background information directly to the audience.

Whether someone prefers one style over another is subjective, but the principle remains useful: people often learn faster when they can see a concept in action rather than read a description of it.

For example, rather than explaining what a gateway does in abstract terms, showing a simple workflow with a screenshot or diagram and then explaining the outcome would help many users understand the concept immediately.

The AI-generated explanation I posted earlier was useful to me for exactly that reason. The XOR/OR/AND comparison wasn't valuable because it was technically perfect, it was valuable because it provided examples and context that made the concepts easier to grasp.

I think the documentation would benefit greatly from:

• More real-world examples
• More diagrams and flowcharts
• Side-by-side comparisons of similar concepts
• Common use cases and patterns
• "Here's a problem, here's how you solve it" style explanations

The existing documentation contains a lot of useful information, but users often have to assemble the puzzle themselves. A few more guided examples could make the learning experience significantly smoother, especially for new users.

i can tell you're a man of few words, and that's fine, use images, they tell 1000 words



If I had to summarise my feedback in one sentence, I'd love the documentation to aim a little more for The Dark Knight and a little less for Aquaman 😄.