PR review feedback

docs/developer/advanced/sharing-saved-objects.asciidoc

@@ -40,9 +40,9 @@ Existing, isolated object types will need to go through a special _conversion pr
 version 8.0. Once objects are converted, they can easily be switched to become fully shareable in any future release. This conversion will
 change the IDs of any existing objects that are not in the Default space. Changing object IDs itself has several knock-on effects:
 
-* Nonstandard links to other objects can break - _mitigated by step 1_
-* "Deep link" pages (URLs) to objects can break - _mitigated by steps 2/3_
-* Encrypted objects may not be able to be decrypted - _mitigated by step 5_
+* Nonstandard links to other objects can break - _mitigated by <<sharing-saved-objects-step-1>>_
+* "Deep link" pages (URLs) to objects can break - _mitigated by <<sharing-saved-objects-step-2>> and <<sharing-saved-objects-step-3>>_
+* Encrypted objects may not be able to be decrypted - _mitigated by <<sharing-saved-objects-step-5>>_
 
 *To be perfectly clear: these effects will all be mitigated _if and only if_ you follow the steps below!*
 
@@ -69,11 +69,12 @@ If your objects store _any_ links to other objects (with an object type/ID), you
 [[sharing-saved-objects-step-1]]
 === Step 1
 
-⚠️ This step *must* be included no later than the 7.16 release. ⚠️
+⚠️ This step *must* be completed no later than the 7.16 release. ⚠️
 
 > *Ensure all object links use the root-level `references` field*
 
-If you answered "Yes" to <<sharing-saved-objects-q1>> above, you need to make sure that your object links are _only_ stored in the root-level `references` field. When a given object's ID is changed, this field will be updated accordingly for other objects.
+If you answered "Yes" to <<sharing-saved-objects-q1>>, you need to make sure that your object links are _only_ stored in the root-level
+`references` field. When a given object's ID is changed, this field will be updated accordingly for other objects.
 
 The image below shows two different examples of object links from a "case" object to an "action" object. The top shows the incorrect way to link to another object, and the bottom shows the correct way.
 
@@ -115,7 +116,7 @@ NOTE: Reminder, don't forget to add unit tests and integration tests!
 > *Are there any "deep links" to these objects?*
 
 A deep link is a URL to a page that shows a specific object. End-users may bookmark these URLs or schedule reports with them, so it is
-critical to ensure that these URLs continue working. The image below shows an example of a deep link.
+critical to ensure that these URLs continue working. The image below shows an example of a deep link to a Canvas workpad object:
 
 image::images/sharing-saved-objects-q2.png["Sharing Saved Objects deep link example"]
 
@@ -125,14 +126,14 @@ Dashboard _and_ a filter for an Index Pattern.
 [[sharing-saved-objects-step-2]]
 === Step 2
 
-⚠️ This step will preferably be included in the 7.16 release; it *must* be included no later than the 8.0 release. ⚠️
+⚠️ This step will preferably be completed in the 7.16 release; it *must* be completed no later than the 8.0 release. ⚠️
 
 > *Update your code to use the new SavedObjectsClient `resolve()` method instead of `get()`*
 
-If you answered "Yes" to <<sharing-saved-objects-q2>> above, you need to make sure that when you use the SavedObjectsClient to fetch an
-object using its ID, you use a different API to do so. The existing `get()` function will only find an object using its current ID. To make
-sure your existing deep link URLs don't break, you should use the new `resolve()` function;
-<<sharing-saved-objects-faq-legacy-url-alias,this attempts to find an object using its old ID _and_ its current ID>>.
+If you answered "Yes" to <<sharing-saved-objects-q2>>, you need to make sure that when you use the SavedObjectsClient to fetch an object
+using its ID, you use a different API to do so. The existing `get()` function will only find an object using its current ID. To make sure
+your existing deep link URLs don't break, you should use the new `resolve()` function; <<sharing-saved-objects-faq-legacy-url-alias,this
+attempts to find an object using its old ID _and_ its current ID>>.
 
 In a nutshell, if your deep link page had something like this before:
 
@@ -163,7 +164,7 @@ passed to your client-side code, and you should update your UI accordingly in th
 [[sharing-saved-objects-step-3]]
 === Step 3
 
-⚠️ This step will preferably be included in the 7.16 release; it *must* be included no later than the 8.0 release. ⚠️
+⚠️ This step will preferably be completed in the 7.16 release; it *must* be completed no later than the 8.0 release. ⚠️
 
 > *Update your _client-side code_ to correctly handle the three different `resolve()` outcomes*
 
@@ -283,7 +284,7 @@ NOTE: Reminder, don't forget to add unit tests and functional tests!
 [[sharing-saved-objects-step-4]]
 === Step 4
 
-⚠️ This step must be included in the 8.0 release (no earlier and no later). ⚠️
+⚠️ This step *must* be completed in the 8.0 release (no earlier and no later). ⚠️
 
 > *Update your _server-side code_ to convert these objects to become "share-capable"*
 
@@ -306,17 +307,17 @@ NOTE: Reminder, don't forget to add integration tests!
 
 > *Are these objects encrypted?*
 
-Saved objects can optionally be encrypted by using the Encrypted Saved Objects plugin. Very few object types are encrypted, so most plugin
-developers will not be affected.
+Saved objects can optionally be <<xpack-security-secure-saved-objects,encrypted>> by using the Encrypted Saved Objects plugin. Very few
+object types are encrypted, so most plugin developers will not be affected.
 
 [[sharing-saved-objects-step-5]]
 === Step 5
 
-⚠️ This step *must* be included in the 8.0 release (no earlier and no later). ⚠️
+⚠️ This step *must* be completed in the 8.0 release (no earlier and no later). ⚠️
 
 > *Update your _server-side code_ to add an Encrypted Saved Object (ESO) migration for these objects*
 
-If you answered "Yes" to <<sharing-saved-objects-q3>> above, you need to take additional steps to make sure that your objects can still be
+If you answered "Yes" to <<sharing-saved-objects-q3>>, you need to take additional steps to make sure that your objects can still be
 decrypted after the conversion process. Encrypted saved objects use some fields as part of "additionally authenticated data" (AAD) to defend
 against different types of cryptographic attacks. The object ID is part of this AAD, and so it follows that the after the object's ID is
 changed, the object will not be able to be decrypted with the standard process.
@@ -352,7 +353,7 @@ to make that object shareable later on when the time is right.
 A developer can easily flip a switch to make a share-capable object into a shareable one, since these are both serialized the same way.
 However, we envision that each consumer will need to enact their own plan and make additional UI changes when making an object shareable.
 For example, some users may not have access to the Saved Objects Management page, but we still want those users to be able to see what
-space(s) their objects exist them and share them to other spaces. Each application should add the appropriate UI controls to handle this.
+space(s) their objects exist in and share them to other spaces. Each application should add the appropriate UI controls to handle this.
 
 
 [[sharing-saved-objects-faq-changing-object-ids]]
@@ -378,8 +379,15 @@ As mentioned in <<sharing-saved-objects-q2>>, some URLs may contain multiple obj
 These should be handled on a case-by-case basis at the plugin owner's discretion. A good rule of thumb is:
 
 * The "primary" object on the page should always handle the three `resolve()` outcomes as described in <<sharing-saved-objects-step-3>>.
-* Any "secondary" objects on the page should usually handle the first two outcomes the same way, but may vary its behavior for the
-`'conflict'` outcome to ignore it throw an error instead. In the case of an error, an actionable message should be shown to the user.
+* Any "secondary" objects on the page may handle the outcomes differently. If the secondary object ID is not important (for example, it just
+  functions as a page anchor), it may make more sense to ignore the different outcomes. If the secondary object _is_ important but it is not
+  directly represented in the UI, it may make more sense to throw a descriptive error when a `'conflict'` outcome is encountered.
+  - If the secondary object is resolved by an external service (such as the index pattern service), the service should simply make the full
+  outcome available to consumers.
+
+Ideally, if a secondary object on a deep link page resolves to an `'aliasMatch'` outcome, the consumer should redirect the user to a URL
+with the new ID and display a toast message. The reason for this is that we don't want users relying on legacy URL aliases more often than
+necessary. However, such handling of secondary objects is not considered critical for the 8.0 release.
 
 [[sharing-saved-objects-faq-legacy-url-alias]]
 ==== 4. What is a "legacy URL alias"?