diff --git a/docs/index.asciidoc b/docs/index.asciidoc
index d8e986d4..3d96e233 100644
--- a/docs/index.asciidoc
+++ b/docs/index.asciidoc
@@ -47,7 +47,14 @@ NOTE: Some multi-pipeline configurations such as logstash-to-logstash over http(
 
 Events that _fail_ ingest pipeline processing will be tagged with `_ingest_pipeline_failure`, and their `[@metadata][_ingest_pipeline_failure]` will be populated with details as a key/value map.
 
-IMPORTANT: This plugin requires minimum Java 17 and Logstash 8.7.0 versions.
+[id="plugins-{type}s-{plugin}-requirements"]
+===== Requirements and upgrade guidance
+
+- This plugin requires Java 17 minimum with {ls} `8.x` versions and Java 21 minimum with {ls} `9.x` versions.
+- When you upgrade the {stack}, upgrade {ls} (or this plugin specifically) _before_ you upgrade {kib}.
+  (Note that this requirement is a departure from the typical {stack} https://www.elastic.co/guide/en/elastic-stack/current/installing-elastic-stack.html#install-order-elastic-stack[installation order].) 
++
+The {es}-{ls}-{kib} installation order ensures the best experience with {agent}-managed pipelines, and embeds functionality from a version of {es} Ingest Node that is compatible with the plugin version (`major`.`minor`).   
 
 [id="plugins-{type}s-{plugin}-es-tips"]
 ===== Using `filter-elastic_integration` with `output-elasticsearch`