feat(experiments): add documentation for retention metric.

Author: rodrigoi

contents/docs/experiments/metrics.mdx

@@ -10,7 +10,7 @@ Once you've created your experiment, you can assign metrics to let you evaluate
 
 ## Metric types
 
-PostHog supports three types of metrics to measure different aspects of your experiment's impact. Choose the metric type that best aligns with your hypothesis.
+PostHog supports four types of metrics to measure different aspects of your experiment's impact. Choose the metric type that best aligns with your hypothesis.
 
 ### Funnel
 
@@ -61,6 +61,39 @@ Common use cases:
 
 Both the numerator and denominator support all aggregation methods (count, sum, average, unique values). You can even use the same event with different properties for each part of the ratio, such as dividing total revenue by total quantity sold from purchase events.
 
+### Retention
+
+Use retention metrics to measure if users come back to perform a specific action within a defined time window after an initial action. This is ideal for measuring engagement patterns, feature stickiness, and long-term user behavior.
+
+How it works:
+1. Define a **start event** (e.g., user signs up, completes onboarding, makes first purchase)
+2. Define a **completion event** (e.g., user logs in, uses a feature, makes another purchase)
+3. Set a **retention window** specifying when the completion event should occur (e.g., between 1 and 7 days after the start event)
+4. Each user either completes the action within the window (retained) or doesn't (not retained)
+5. We calculate the retention rate (proportion of users who returned) for each variant
+6. Statistical significance is determined using the difference in retention rates between variants
+
+**Retention window:**
+The retention window has two boundaries that define when the completion event counts:
+- **Start boundary** (inclusive): Earliest time after the start event (e.g., 1 day)
+- **End boundary** (inclusive): Latest time after the start event (e.g., 7 days means up to and including day 7)
+
+For example, a "1 to 7 days" retention window means the completion event must occur at least 1 full day after the start event, and up to 7 full days after (days 1-7 all count).
+
+**How time periods are calculated:**
+For day-based windows, PostHog compares calendar days rather than exact 24-hour periods. This means the retention window captures any time within the specified days. For example, a "7 days" window includes any completion event that occurs on the 7th calendar day after the start event, regardless of the specific times. Hour-based windows work the same way, using whole hours (e.g., 2 PM to 3 PM) rather than exact 60-minute durations.
+
+**Start handling:**
+You can choose how PostHog identifies the start event for each user:
+- **First seen**: Uses the first occurrence of the start event (ideal for one-time actions like signup)
+- **Last seen**: Uses the last occurrence of the start event (useful for recurring actions)
+
+Common use cases:
+- **Onboarding effectiveness**: Track if users who complete onboarding return within 7 days
+- **Feature stickiness**: Measure if users who try a new feature come back to use it again
+- **Re-engagement**: Test if marketing campaigns bring back dormant users
+- **Churn reduction**: Measure if changes reduce the time until users return
+
 ## Outlier handling
 
 You can limit the impact of extreme values by capping metric data at specified percentile thresholds using configurable lower and upper bounds. Metric data beyond those thresholds aren't included in experiment calculations.