The docs on compensation are hard to understand, especially if you do not know the compensation behavior in detail as given in the spec

Ideas:

• there should be a general introduction on compensation before the individual types of events are discussed. Many of the general compensation aspects are currently described in http://stage.docs.camunda.org/api-references/bpmn20/#events-cancel-and-compensation-events-intermediate-throwing-compensation-event
• The descriptions of the compensation event types can be improved. For example http://stage.docs.camunda.org/api-references/bpmn20/#events-cancel-and-compensation-events-compensation-boundary-event and http://stage.docs.camunda.org/api-references/bpmn20/#events-cancel-and-compensation-events-compensation-start-event go right into details before describing the use case that can be solved by them