I brought up this question during February’s question corner with @nikku . The BPMN spec (section 8.2.2) allows for specifying multiple documentation elements on BaseElements, distinguishing them by an id. In its current state, the Modeler does not allow defining multiple elements graphically. Nico’s response to the question was - understandably - that not everything is supported or even makes sense and that any additional elements entered in the XML would be preserved by the Modeler. Unfortunately, the latter is not the case - the attached model contains a secondary Documentation element for the task, which is preserved when loading the diagram, but wiped out when making any change to the element’s primary documentation. documentation-test.bpmn (2.2 KB)
@nikku was interested in the use case for having multiple, so here it is
Documentation can serve multiple audiences. First and foremost, the Documentation element is often used to provide general documentation about elements or instructions to users performing user tasks. In the user task case, an important feature is that the documentation also enjoys substitution of expressions in the documentation on task creation. But what if, besides this documentation, you also need to document parts of the process for other audiences (for instance, business departments such as auditors), which should not be shown by default to users? You could use a custom extension to capture the documentation, and that would most likely be correctly preserved by the Modeler. However, substitution would not work and since the specification already provides for this, support for it in the Modeler would be even nicer.
I realise there might be complications implementing this, since there is no “primary” element, but I wanted to post the case first before considering implementation details.
Happy to hear ideas and suggestions!