diff --git a/docs/breaking-changes.asciidoc b/docs/breaking-changes.asciidoc
deleted file mode 100644
index 699da3c2d574f..0000000000000
--- a/docs/breaking-changes.asciidoc
+++ /dev/null
@@ -1,12 +0,0 @@
-[[breaking-changes]]
-== Breaking Changes
-
-This section discusses the changes that you need to be aware of when migrating
-your application from one version of Kibana to another.
-
-[[breaking-changes-5.0]]
-=== Breaking changes in 5.0
-* {k4pull}8013[Pull Request 8013]: Kibana binds to localhost by default
-* {k4pull}7855[Pull Request 7855]: Markdown headers require a space between the final hash and title
-* {k4pull}7308[Pull Request 7308]: Debian and rpm packages install assets to `/usr/share/kibana`, and configuration to `/etc/kibana`
-* {k4pull}6402[Pull Request 6402]: The plugin installer now has its own executable, it can be found at `/bin/kibana-plugin`
\ No newline at end of file
diff --git a/docs/index.asciidoc b/docs/index.asciidoc
index 20d859d893929..afcb391a46595 100644
--- a/docs/index.asciidoc
+++ b/docs/index.asciidoc
@@ -16,7 +16,7 @@ include::setup.asciidoc[]
 
 include::getting-started.asciidoc[]
 
-include::breaking-changes.asciidoc[]
+include::migration/index.asciidoc[]
 
 include::plugins.asciidoc[]
 
diff --git a/docs/migration/index.asciidoc b/docs/migration/index.asciidoc
new file mode 100644
index 0000000000000..1a20cb65a058f
--- /dev/null
+++ b/docs/migration/index.asciidoc
@@ -0,0 +1,8 @@
+[[breaking-changes]]
+== Breaking Changes
+
+This section discusses the changes that you need to be aware of when migrating
+your application from one version of Kibana to another.
+
+include::migrate_5_0.asciidoc[]
+
diff --git a/docs/migration/migrate_5_0.asciidoc b/docs/migration/migrate_5_0.asciidoc
new file mode 100644
index 0000000000000..b9b0c4b6318d5
--- /dev/null
+++ b/docs/migration/migrate_5_0.asciidoc
@@ -0,0 +1,45 @@
+[[breaking-changes-5.0]]
+=== Breaking changes in 5.0
+
+==== Kibana binds to localhost by default
+{k4pull}8013[Pull Request 8013]
+
+*Details:* Kibana (like Elasticsearch) now binds to localhost for security purposes instead of 0.0.0.0 (all addresses). Previous binding to 0.0.0.0 also caused issues for Windows users.
+
+*Impact:* If you are running Kibana inside a container/environment that does not allow localhost binding, this will cause Kibana not to start up unless server.host is configured in the kibana.yml to a valid IP address/host, etc..
+
+==== Markdown headers
+
+{k4pull}7855[Pull Request 7855]
+
+*Details:* As part of addressing the security issue https://www.elastic.co/community/security[ESA-2016-03] (CVE-2016-1000220) in the Kibana product, the markdown version has been bumped.
+
+*Impact:* As a result of the fix to ESA-2016-03, there is a slight change in the markdown format for headers.
+
+Previously, headers are defined using `###` followed by the title:
+
+ ###Packetbeat:
+    [Dashboard](/#/dashboard/Packetbeat-Dashboard)
+    [Web transactions](/#/dashboard/HTTP)
+
+It should now be defined as follows (with a space between ### and the title):
+
+ ### Packetbeat:
+     [Dashboard](/#/dashboard/Packetbeat-Dashboard)
+     [Web transactions](/#/dashboard/HTTP)
+
+==== Linux package install directories
+
+{k4pull}7308[Pull Request 7308]
+
+*Details:* To align with the Elasticsearch packages, Kibana now installs binaries under `/usr/share/kibana` and configuration files under `/etc/kibana`. Previously they were both located under `/opt/kibana`.
+
+*Impact:* Apart from learning the new location of Kibana binaries and configuration files, you may have to update your automation scripts as needed.
+
+==== The plugin installer now has its own executable
+
+{k4pull}6402[Pull Request 6402]
+
+*Details:* The new installer can be found at `/bin/kibana-plugin`. When installing/removing Kibana plugins, you will now call `kibana-plugin` instead of the main kibana script.
+
+*Impact:* You may have to update your automation scripts.
\ No newline at end of file