Documentation Element (1 or more) and Camunda Extension to "Type" the Documentation

A common usage pattern in the Camunda tasklist is to the use the User Task documentation element to provide a description of what the task is about for the end user.
https://docs.camunda.org/manual/7.5/reference/bpmn20/tasks/user-task/#description

BPMN spec shows that 1 or more documentation elements can be supported on all bpmn elements:

8.2.2 Documentation
All BPMN elements that inherit from the BaseElement will have the capability, through the Documentation element, to have one (1) or more text descriptions of that element.

The Documentation element inherits the attributes and model associations of BaseElement (see Table 8.5). Table 8.6 presents the additional attributes of the Documentation element.

Has anyone done something like support more than one documentation element instance on a User Task and providing some sort of extension that “types” the instances so you can do something such as:

  1. business configuration documentation
  2. user action documentation
  3. system/admin
  4. etc.

The point being that we could start to generate “Documentation” micro-sites for a BPMN file based on the configuration and documentation elements, But when we use the user task documentation element for user docs that are displayed on the tasklist, it starts to become problematic. :).

Thoughts?
@camunda
Thanks!

@camunda anyone able to provide some insight into this?

Looking to start building a auto documentation generator based on the documentation fields, but I do not want to execute on this if you feel documentation field should have more execution uses such as the current use case of the Task Description.

Thanks!!

Okay started some more testing on this. The Model API supports multiple Documentation Tags. @nikku any specifics on why Modeler does not support Multiple Documentation instances?

Thanks @camunda

example:
I am pulling this from the model API:

Technically the BPMN spec allows a type to be attached to a documentation field via the textFormat attribute. You could hijack that to distinguish different kinds of documentation. We take this approach in the bpmn-js comments example.

The modeler, as you mentioned will only show and edit the first documentation field, regardless of how many are present on an element.

We decided to support only one documentation tag for simplicity. In most cases it is hard to argue, why you’d need more than one. This is especially relevant because visible documentation is often done using Text Annotations instead.

What we could think of in the future is making the one documentation field without text format or with text format text/plain editable by the user. This would allow you to ship arbitrary other documentation fields and auto generate them without the modeler interfering.

1 Like

@nikku thanks! good ideas.