diff --git a/packages/flutter/lib/src/widgets/performance_overlay.dart b/packages/flutter/lib/src/widgets/performance_overlay.dart
index 0205071471..d4cdb21540 100644
--- a/packages/flutter/lib/src/widgets/performance_overlay.dart
+++ b/packages/flutter/lib/src/widgets/performance_overlay.dart
@@ -7,6 +7,18 @@ import 'package:flutter/rendering.dart';
 import 'framework.dart';
 
 /// Displays performance statistics.
+///
+/// The overlay show two time series. The first shows how much time was required
+/// on this thread to produce each frame. The second shows how much time was
+/// required on the GPU thread to produce each frame. Ideally, both these values
+/// would be less than the total frame budget for the hardware on which the app
+/// is running. For example, if the hardware has a screen that updates at 60 Hz,
+/// each thread should ideally spend less than 16 ms producing each frame. This
+/// ideal condition is indicated by a green vertical line for each thread.
+///
+/// The simplest way to show the performance overlay is to set
+/// [MaterialApp.showPerformanceOverlay] or [WidgetsApp.showPerformanceOverlay]
+/// to `true`.
 class PerformanceOverlay extends LeafRenderObjectWidget {
   // TODO(abarth): We should have a page on the web site with a screenshot and
   // an explanation of all the various readouts.