clarify how delay is calculated (kubernetes-sigs#907)

* clarify how delay is calculated

* improve writing

* fix typo

Author: caozhuozi

site/content/en/docs/user/stages-configuration.md

@@ -88,6 +88,7 @@ Please note that `weight` only takes effect among stages with same `resourceRef`
 Additionally, the `delay` field in a Stage resource allows users to specify a delay before the stage is applied,
 and introduce jitter to the delay to specify the latest delay time to make the simulation more realistic.
 This can be useful for simulating real-world scenarios where events do not always happen at the same time.
+Please refer to [How Delay is Calculated] for more details.
 
 By configuring the `delay`, `selector`, and `next` fields in a Stage, you can control when and how the stage is applied,
 providing a flexible and scalable way to simulate real-world scenarios in your Kubernetes cluster.
@@ -152,6 +153,45 @@ if a "Change Stage" is matched. The update action itself consequently causes a n
 However, this event-driven approach to applying Stages has a limitation: `kwok` won’t apply a Stage until a new event associated with that resource is received. To address the limitation,
 users can utilize the `immediateNextStage` field to make the controller apply Stages immediately rather than waiting for an event pushed from the apiserver.
 
+## How Delay is Calculated
+
+The delay time of applying a Stage is obtained by adding a constant time period and a randomized interval,
+which will be denoted by *duration* and *jitter* respectively in the following.
+
+- `durationMilliseconds`: provides *duration*.
+- `jitterDurationMilliseconds`: calculates *jitter* by *random*(`jitterDurationMilliseconds`-*duration*).
+  It shall be larger than `durationMilliseconds` if you want to inject jitter to the delay.
+  Otherwise, it will be used directly as the delay time without any randomization.
+
+`kwok` also provides other fields to flexibly handle more situations. They are used to extract
+and parse a RFC3339 timestamp field of a resource to help determine the delay time dynamically.
+
+- `durationFrom`: calculates *duration* by `durationFrom`-*now*
+- `jitterDurationFrom`: calculates *jitter* by *random*(`jitterDurationFrom`-*now*-*duration*),
+  where *now* is the timestamp when the delay starts.
+
+{{< hint "info" >}}
+`durationFrom` and `jitterDurationFrom` have a higher priority than `durationMilliseconds`
+and `jitterDurationMilliseconds` if both are set.
+{{< /hint >}}
+
+Let’s explain a little bit about the motivation behind these two advanced fields.
+But before that, for a better understanding, we briefly describe how kubelet "delete" a pod from a node.
+
+Here are the steps to remove a pod in Kubernetes:
+
+1. Execute the command `kubectl delete pod`. The apiserver receives the deletion request but does not immediately remove the corresponding pod resource from etcd.
+2. The apiserver sets the `metadata.deletionTimestamp` field to the time the request was issued plus a short period, defined by `metadata.deletionGracePeriodSeconds` (default 30s).
+3. The kubelet detects a non-null `metadata.deletionTimestamp` for a pod and starts to send a `TERM` signal to the main process of the container.
+4. If the `metadata.deletionTimestamp` expires before the process stops by itself, the main process is then terminated using the `KILL` signal.
+5. After all the containers in the pod have stopped running, the kubelet sends a force deletion request to the apiserver.
+6. The apiserver removes the pod object from etcd.
+
+To simulate this situation, you can set `jitterDurationFrom` of a "Delete Stage" (`next.delete: true`) to point to `metadata.deletionTimestamp`.
+This will cause the deletion operation to occur at a random moment before `metadata.deletionTimestamp` expires.
+You can also let `kwok` perform the deletion in a deterministic way by pointing `durationFrom` to `metadata.deletionTimple`,
+making the deletion happen exactly at `metadata.deletionTimple`.
+
 ## Examples
 
 ### Node Stages
@@ -216,3 +256,4 @@ This example shows how to configure the simplest and fastest stages of Pod resou
 [General Pod Stages]: https://github.com/kubernetes-sigs/kwok/tree/main/kustomize/stage/pod/general
 [Stage API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Stage
 [Resource Lifecycle Simulation Controller]: {{< relref "/docs/design/architecture" >}}
+[How Delay is Calculated]: {{< relref "/docs/user/stages-configuration#how-delay-is-calculated" >}}