From 5ef251f2f29274763ea15558750085682afe029b Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Wed, 29 Jan 2020 16:52:40 -0800
Subject: [PATCH] [DOCS] Minor fixes in transform documentation (#51633)

---
 .../transform/ecommerce-tutorial.asciidoc     | 20 ++++++++---
 .../authorization/built-in-roles.asciidoc     | 34 +++++++++----------
 2 files changed, 31 insertions(+), 23 deletions(-)

diff --git a/docs/reference/transform/ecommerce-tutorial.asciidoc b/docs/reference/transform/ecommerce-tutorial.asciidoc
index 6a640f5bc37a3..958067edb0613 100644
--- a/docs/reference/transform/ecommerce-tutorial.asciidoc
+++ b/docs/reference/transform/ecommerce-tutorial.asciidoc
@@ -81,8 +81,11 @@ If you want to use more complex queries, you can create your {dataframe} from a
 {kibana-ref}/save-open-search.html[saved search].
 
 If you prefer, you can use the
-<<preview-transform,preview {transforms} API>>:
+<<preview-transform,preview {transforms} API>>.
 
+.API example
+[%collapsible]
+====
 [source,console]
 --------------------------------------------------
 POST _transform/_preview
@@ -131,6 +134,7 @@ POST _transform/_preview
 }
 --------------------------------------------------
 // TEST[skip:set up sample data]
+====
 --
 
 . When you are satisfied with what you see in the preview, create the
@@ -153,9 +157,11 @@ entities have changed. In general, it's a good idea to use the ingest timestamp
 field. In this example, however, you can use the `order_date` field.
 
 If you prefer, you can use the
-<<put-transform,create {transforms} API>>. For
-example:
+<<put-transform,create {transforms} API>>.
 
+.API example
+[%collapsible]
+====
 [source,console]
 --------------------------------------------------
 PUT _transform/ecommerce-customer-transform
@@ -211,6 +217,7 @@ PUT _transform/ecommerce-customer-transform
 }
 --------------------------------------------------
 // TEST[skip:setup kibana sample data]
+====
 --
 
 . Start the {transform}.
@@ -229,14 +236,17 @@ image::images/manage-transforms.jpg["Managing {transforms} in {kib}"]
 
 Alternatively, you can use the
 <<start-transform,start {transforms}>> and
-<<stop-transform,stop {transforms}>> APIs. For
-example:
+<<stop-transform,stop {transforms}>> APIs.
 
+.API example
+[%collapsible]
+====
 [source,console]
 --------------------------------------------------
 POST _transform/ecommerce-customer-transform/_start
 --------------------------------------------------
 // TEST[skip:setup kibana sample data]
+====
 
 TIP: If you chose a batch {transform}, it is a single operation that has a
 single checkpoint. You cannot restart it when it's complete. {ctransforms-cap}
diff --git a/x-pack/docs/en/security/authorization/built-in-roles.asciidoc b/x-pack/docs/en/security/authorization/built-in-roles.asciidoc
index 8bd2eb85754fb..af1c8f2c46487 100644
--- a/x-pack/docs/en/security/authorization/built-in-roles.asciidoc
+++ b/x-pack/docs/en/security/authorization/built-in-roles.asciidoc
@@ -37,29 +37,17 @@ suitable for writing beats output to {es}.
 
 --
 
-[[built-in-roles-transform-admin]] `transform_admin` :: 
-Grants `manage_transform` cluster privileges, which enable you to manage 
-{transforms}. This role also includes all 
-{kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
-
-[[built-in-roles-transform-user]] `transform_user` ::
-Grants `monitor_transform` cluster privileges, which enable you to use 
-{transforms}. This role also includes all
-{kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
-
 [[built-in-roles-data-frame-transforms-admin]] `data_frame_transforms_admin` ::
-(This role is deprecated, please use the 
-<<built-in-roles-transform-admin,`transform_admin`>> role instead.) Grants 
-`manage_data_frame_transforms` cluster privileges, which enable you to manage 
-{transforms}. This role also includes all
+Grants `manage_data_frame_transforms` cluster privileges, which enable you to
+manage {transforms}. This role also includes all
 {kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
+deprecated:[7.5.0,"Replaced by <<built-in-roles-transform-admin,`transform_admin`>>"].
 
 [[built-in-roles-data-frame-transforms-user]] `data_frame_transforms_user` ::
-(This role is deprecated, please use the 
-<<built-in-roles-transform-user,`transform_user`>> role instead.) Grants 
-`monitor_data_frame_transforms` cluster privileges, which enable you to use 
-{transforms}. This role also includes all
+Grants `monitor_data_frame_transforms` cluster privileges, which enable you to
+use {transforms}. This role also includes all
 {kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
+deprecated:[7.5.0,"Replaced by <<built-in-roles-transform-user,`transform_user`>>"].
 
 [[built-in-roles-ingest-user]] `ingest_admin` ::
 Grants access to manage *all* index templates and *all* ingest pipeline configurations.
@@ -153,6 +141,16 @@ the `superuser` role can also manage users and roles and
 <<run-as-privilege, impersonate>> any other user in the system. Due to the
 permissive nature of this role, take extra care when assigning it to a user.
 
+[[built-in-roles-transform-admin]] `transform_admin`:: 
+Grants `manage_transform` cluster privileges, which enable you to manage 
+{transforms}. This role also includes all 
+{kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
+
+[[built-in-roles-transform-user]] `transform_user`::
+Grants `monitor_transform` cluster privileges, which enable you to use 
+{transforms}. This role also includes all
+{kibana-ref}/kibana-privileges.html[Kibana privileges] for the {ml-features}.
+
 [[built-in-roles-transport-client]] `transport_client`::
 Grants the privileges required to access the cluster through the Java Transport
 Client. The Java Transport Client fetches information about the nodes in the