diff --git a/platform/statistics/src/com/intellij/internal/statistic/IdeActivity.kt b/platform/statistics/src/com/intellij/internal/statistic/IdeActivity.kt
index b700950bae50..6c85547cf915 100644
--- a/platform/statistics/src/com/intellij/internal/statistic/IdeActivity.kt
+++ b/platform/statistics/src/com/intellij/internal/statistic/IdeActivity.kt
@@ -16,7 +16,8 @@ private val LOG = Logger.getInstance(IdeActivity::class.java)
 
 internal enum class IdeActivityState { NOT_STARTED, STARTED, FINISHED }
 
-@Deprecated("Use com.intellij.internal.statistic.StructuredIdeActivity instead")
+@Deprecated("Use com.intellij.internal.statistic.StructuredIdeActivity instead. " +
+            "It allows us to generate events scheme from the product code and ensures that only data matching the scheme is being sent.")
 @ApiStatus.Internal
 class IdeActivity @JvmOverloads constructor(private val projectOrNullForApplication: Project?,
                                             private val group: String,
diff --git a/platform/statistics/src/com/intellij/internal/statistic/StructuredIdeActivity.kt b/platform/statistics/src/com/intellij/internal/statistic/StructuredIdeActivity.kt
index fb3aba050f43..4468afeb1c7a 100644
--- a/platform/statistics/src/com/intellij/internal/statistic/StructuredIdeActivity.kt
+++ b/platform/statistics/src/com/intellij/internal/statistic/StructuredIdeActivity.kt
@@ -15,6 +15,18 @@ import java.util.concurrent.atomic.AtomicInteger
 
 private val LOG = Logger.getInstance(StructuredIdeActivity::class.java)
 
+/**
+ * New style API to record information about process.
+ * It allows you to record start/finish events, calculate duration and link them by common id.
+ *
+ * To record a process:
+ * - Register ide activity in event log group (see [com.intellij.internal.statistic.eventLog.EventLogGroup.registerIdeActivity]).
+ * - Use [com.intellij.internal.statistic.IdeActivityDefinition.started] or
+ * [com.intellij.internal.statistic.IdeActivityDefinition.startedAsync] to record start event and
+ * [com.intellij.internal.statistic.StructuredIdeActivity.finished] to record finish event.
+ *
+ * See example in dev-guide/fus-collectors.md.
+ */
 @ApiStatus.Internal
 class StructuredIdeActivity internal constructor(private val projectOrNullForApplication: Project?,
                                                  private val ideActivityDefinition: IdeActivityDefinition) {