AIP-193: Update the Help section

Significant changes here (all up for discussion):

- Explicitly include Status.message as well as LocalizedMessage.message
- Remove the standardized https://cloud.google.com/PRODUCT/docs/ERROR-REASON format requirement
- Require the description to be suitable as text for a link
- Require the description to be plain text
- Require the URL to be absolute and include a scheme
- Add authentication requirements

Author: jskeet

aip/general/0193.md

@@ -204,33 +204,39 @@ to the error. If more information is needed than can reasonably fit in this
 payload, then additional resolution information **must** be provided in
 a `Help` payload.  See the [Help](#help) section for guidance.
 
-#### Help payload
+#### Help
 
-When `LocalizedMessage.message` doesn’t provide the user sufficient
+When other textual error messages (in `Status.message` or
+`LocalizedMessage.message`) don't provide the user sufficient
 context or actionable next steps, or if there are multiple points of
 failure that need to be considered in troubleshooting, a link to
 supplemental troubleshooting documentation **must** be provided in the
 `Help` payload.
 
 Provide this information in addition to a clear problem definition and
-actionable resolution, not as an alternative to them; for example.
+actionable resolution, not as an alternative to them. The linked
+documentation **must** clearly relate to the error. If a single page
+contains information about multiple errors, the
+[`ErrorInfo.reason`](#errorinfo) value **must** be used to narrow down
+the relevant information.
 
-**Note:** For more information, see the troubleshooting documentation:
-[https://cloud.google.com/compute/docs/resource-error][resource-error].
+The `description` field is a textual description of the linked information.
+This **must** be suitable to display to a user as text for a hyperlink.
+This **must** be plain text (not HTML, Markdown etc).
 
-[Help payload][Help]
+Example `description` value: `"Troubleshooting documentation for STOCKOUT errors"`
 
-Details of this object are summarized in the following fields, field
-descriptions, and examples:
+The `url` field is the URL to link to. This **must** be an absolute URL,
+including scheme.
 
-- `description string`
-  - Describes what the link offers.
-  - *Example*: "Troubleshooting documentation for STOCKOUT errors"
-- `url string`
-  - The URL of the link. For error documentation this must follow the
-    standardized format listed in the following example.
-  - *Example*:
-      https://cloud.google.com/PRODUCT/docs/ERROR-REASON
+Example `url` value:
+`"https://cloud.google.com/compute/docs/resource-error"`
+
+For publicly-documented services, even those with access controls on actual
+usage, the linked content **must** be accessible without authentication.
+
+For privately-documented services, the linked content **may** require
+authentication.
 
 ### Error messages