Merge pull request #5031 from Icinga/fix/doc-acknowledgements-5029

Docs: Fixes and enhancements for acks, comments and downtimes

fixes #5029
fixes #5030

doc/8-advanced-topics.md

@@ -53,12 +53,39 @@ is removed (may happen before or after the actual end time!).
 
 ### <a id="scheduling-downtime"></a> Scheduling a downtime
 
-This can either happen through a web interface or by sending an [external command](14-features.md#external-commands)
+You can schedule a downtime either by using the Icinga 2 API action
-to the external command pipe provided by the `ExternalCommandListener` configuration.
+[schedule-downtime](#icinga2-api-actions-schedule-downtime) or
+by sending an [external command](14-features.md#external-commands).
+
+
+#### <a id="fixed-downtime"></a> Fixed Downtime
+
+If the host/service changes into a NOT-OK state between the start and
+end time window, the downtime will be marked as `in effect` and
+increases the downtime depth counter.
+
+```
+   |       |         |
+start      |        end
+       trigger time
+```
+
+#### <a id="flexible-downtime"></a> Flexible Downtime
+
+A flexible downtime defines a time window where the downtime may be
+triggered from a host/service NOT-OK state change. It will then last
+until the specified time duration is reached. That way it can happen
+that the downtime end time is already gone, but the downtime ends
+at `trigger time + duration`.
+
+
+```
+   |       |         |
+start      |        end               actual end time
+           |--------------duration--------|
+       trigger time
+```
 
-Fixed downtimes require a start and end time (a duration will be ignored).
-Flexible downtimes need a start and end time for the time span, and a duration
-independent from that time span.
 
 ### <a id="triggered-downtimes"></a> Triggered Downtimes
 
@@ -100,21 +127,39 @@ add useful information for others on repeating incidents (for example
 "last time syslog at 100% cpu on 17.10.2013 due to stale nfs mount") which
 is primarily accessible using web interfaces.
 
-Adding and deleting comment actions are possible through the external command pipe
+You can add a comment either by using the Icinga 2 API action
-provided with the `ExternalCommandListener` configuration. The caller must
+[add-comment](#icinga2-api-actions-add-comment) or
-pass the comment id in case of manipulating an existing comment.
+by sending an [external command](14-features.md#external-commands).
-
 
 ## <a id="acknowledgements"></a> Acknowledgements
 
-If a problem is alerted and notified, you may signal the other notification
+If a problem persists and notifications have been sent, you can
-recipients that you are aware of the problem and will handle it.
+acknowledge the problem. That way other users will get
+a notification that you're aware of the issue and probably are
+already working on a fix.
+
+Note: Acknowledgements also add a new [comment](#comment-intro)
+which contains the author and text fields.
+
+You can send an acknowledgement either by using the Icinga 2 API action
+[acknowledge-problem](#icinga2-api-actions-acknowledge-problem) or
+by sending an [external command](14-features.md#external-commands).
+
+
+### <a id="sticky-acknowledgements"></a> Sticky Acknowledgements
+
+The acknowledgement is removed if a state change occurs or if the host/service
+recovers (OK/Up state).
+
+If you acknowlege a problem once you've received a `Critical` notification,
+the acknowledgement will be removed if there is a state transition to `Warning`.
+```
+OK -> WARNING -> CRITICAL -> WARNING -> OK
+```
+
+If you prefer to keep the acknowledgement until the problem is resolved (`OK`
+recovery) you need to enable the `sticky` parameter.
 
-By sending an acknowledgement to Icinga 2 (using the external command pipe
-provided with `ExternalCommandListener` configuration) all future notifications
-are suppressed, a new comment is added with the provided description and
-a notification with the type `NotificationFilterAcknowledgement` is sent
-to all notified users.
 
 ### <a id="expiring-acknowledgements"></a> Expiring Acknowledgements