diff --git a/docs/howto/update_major_package_spec.md b/docs/howto/update_major_package_spec.md
index 4bb13d91b9..e69ff7e40e 100644
--- a/docs/howto/update_major_package_spec.md
+++ b/docs/howto/update_major_package_spec.md
@@ -121,6 +121,24 @@ There are two variants of this error:
   between different dashboards, and to allow users to quickly filter using the
   query bar without affecting the provided filters.
 
+### "My Dashboard" contains legacy visualization: "My Visualization" (metric, TSVB)
+
+All visualizations must be created using [Lens](https://www.elastic.co/kibana/kibana-lens) or [Vega](https://www.elastic.co/guide/en/kibana/current/vega.html).
+
+The only exceptions are
+- Markdown panels created from the dashboard application. There are no plans to deprecate these.
+- TSVB markdown. Support will eventually be removed, but this is
+  currently allowed because we do not yet offer an alternative for
+  injecting analytics into markdown. Prefer the dashboard markdown
+  panels when possible.
+- The legacy dashboard controls ("input-control-vis"). These should be replaced
+  with the [new dashboard controls](https://www.elastic.co/guide/en/kibana/current/add-controls.html) but we are not currently
+  enforcing this with tooling.
+
+**Note:** most legacy visualizations can be converted by selecting "Convert to Lens"
+from the dashboard panel context menu or by clicking "Edit visualization in Lens"
+after opening the visualization in the editor.
+
 ## Troubleshooting upgrades to Package Spec v2
 
 ### field (root): Additional property license is not allowed