diff --git a/CHANGELOG.md b/CHANGELOG.md
index 58828200..e4227b1f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
   - Releases from `main` are not desired until we get closer to Stack 9.x, and beginning the changelog with something other than release notes matching the version will prevent the plugin release tooling from allowing publication.
 
 ## 0.1.17
-    - Add `x-elastic-product-origin` header to Elasticsearch requests [#197](https://github.com/elastic/logstash-filter-elastic_integration/pull/197)
+  - Add `x-elastic-product-origin` header to Elasticsearch requests [#197](https://github.com/elastic/logstash-filter-elastic_integration/pull/197)
 
 ## 0.1.16
   - Reflects the Elasticsearch GeoIP changes into the plugin and syncs with Elasticsearch 8.16 branch [#170](https://github.com/elastic/logstash-filter-elastic_integration/pull/170)
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`