Enhance help text for the 'top' command

* Detailing the metrics source
* Connecting to HPA
* Defining its scope

Kubernetes-commit: e54e01e0abbff795a5628f2e845c815e6d43c03f

pkg/cmd/top/top.go

@@ -39,9 +39,31 @@ var (
 	topLong = templates.LongDesc(i18n.T(`
 		Display resource (CPU/memory) usage.
 
-		The top command allows you to see the resource consumption for nodes or pods.
+		This command provides a view of recent resource consumption for nodes and pods.
+		It fetches metrics from the Metrics Server, which aggregates this data from the
+		kubelet on each node. The Metrics Server must be installed and running in the
+		cluster for this command to work.
 
-		This command requires Metrics Server to be correctly configured and working on the server. `))
+		The metrics shown are specifically optimized for Kubernetes autoscaling
+		decisions, such as those made by the Horizontal Pod Autoscaler (HPA) and
+		Vertical Pod Autoscaler (VPA). Because of this, the values may not match those
+		from standard OS tools like 'top', as the metrics are designed to provide a
+		stable signal for autoscalers rather than for pinpoint accuracy.
+
+		When to use this command:
+
+		* For on-the-fly spot-checks of resource usage (e.g. identify which pods
+		  are consuming the most resources at a glance, or get a quick sense of the load
+		  on your nodes)
+		* Understand current resource consumption patterns
+		* Validate the behavior of your HPA or VPA configurations by seeing the metrics
+		  they use for scaling decisions.
+
+		It is not intended to be a replacement for full-featured monitoring solutions.
+		Its primary design goal is to provide a low-overhead signal for autoscalers,
+		not to be a perfectly accurate monitoring tool. For high-accuracy reporting,
+		historical analysis, dashboarding, or alerting, you should use a dedicated
+		monitoring solution.`))
 )
 
 func NewCmdTop(f cmdutil.Factory, streams genericiooptions.IOStreams) *cobra.Command {