BXMSDOC-6416-master: Add multi-DRD content to PAM/DM

[sterobin]

@karreiro @jstastny-cz @hmanwani-rh Ready for your review. Links below.

Links:

• Jira
• Enterprise doc preview
• Community doc preview
• Release note
• Related PR: BXMSDOC-6416-master-kogito: Add multi-DRD content to Kogito #2854

[hmanwani-rh]

@sterobin Have added a few suggestions, rest looks good.

Thank you so much.

[hmanwani-rh]

Can we shorten the descriptions for these options, for example:

• Create: To create a nested DRD
• Add to: To add a node to an existing DRD
• Remove: To remove a node from a nested DRD

[sterobin]

@hmanwani-rh This is the format we use elsewhere for many of the other similar bullet points, even in this doc. Either way, the preferred shortened alternative would actually be "Creates a nested ...", but that removes user action. What you suggest would be more user centric, but just leads to a sentence that the reader expects to be complete, and then ends. So a little jarring/confusing. So I typically use the full version to ensure it's user centric, but this is a topic for group discussion at some point.

[hmanwani-rh]

Suggested change

	. Continue adding and defining any other nested DRDs for your decision model and save the completed DMN file.
	. Continue adding and defining other nested DRDs for your decision model and save the completed DMN file.

[sterobin]

In this case, I like "any" and we use the same at the end of the other DMN model instructions. It suggests a feeling that you might or might not have others to create, and it's up to you. Without "any", we're commanding them to create other ones, but we're really just saying, create any other ones, meaning if needed.

[jstastny-cz]

I don't think we have the DRG tab contents completely right :-/ I got the same understanding as is documented here, but then after discussion with @danielzhe it was made clear that DRG panel should contain all the Decision components that exist across all DRDs. So DRG should serve as sort of an index of all Decision components.
But those changes are supposed to be done in https://issues.redhat.com/browse/KOGITO-2667, which is not probable to land in this release.
@karreiro @danielzhe could you please clarify?

In any case - it would be probably safer to use just DRDs in the Decision breakout example (Decision spanning multiple DRDs) screenshots - not refer to the DRG as the high-level view of the model (cause even though this might be true now, it could set wrong expectations and pose unnecessary burden on users when we change behavior of DRG panel). E.g. dmn-drd-multiple-back-end.png - if Loan Pre-Qualification is moved from DRG to new DRD, it will still hold after KOGITO-2667, if it stays in DRG, it would be not true anymore - cause DRG would contain all the decision components.

[sterobin]

@jstastny-cz I think I follow, but not quite sure. Either way, I think the easier approach for docs is to document what is true today, and then if that changes at some point, update the docs/screenshots accordingly. Otherwise I can't visualize what you're describing and it's difficult to document features that aren't a reality yet. If that Jira is going to be merged by end of this week and we'll have access to the latest UI showing the changes you're describing for this release, then sure, can hold this PR and then update the screenshots accordingly next week. But if this is at risk for this release as you say, then I see no problem in documenting the DMN designer as it is today with how users will see it once released, and then update it as needed for next release. Let me know if I've misunderstood.

[karreiro]

@sterobin @jstastny-cz Given the timeframe the KOGITO-2667 won't be merged this week. Thus, I agree with Stetson, let's document what we have today and change/improve it in the future.

[karreiro]

Thank you, @sterobin.

[jstastny-cz]

Approving, the docs describe well the feature in its current state.