Clean up and promote AIP-193 to published

aip/general/0193.md

@@ -1,7 +1,8 @@
 ---
 id: 193
-state: draft
+state: published
 created: 2019-07-26
+updated: 2024-04-02
 placement:
   category: polish
   order: 30
@@ -29,7 +30,7 @@ assume that the user will know anything about its underlying
 implementation.
 
 Error messages **should** be brief but actionable. Any extra information
-**should** be provided in the `details`field. If even more information
+**should** be provided in the `details` field. If even more information
 is necessary, you **should** provide a link where a reader can get more
 information or ask questions to help resolve the issue. It is also
 important to [set the right tone][writing-tone] when writing messages.
@@ -41,12 +42,6 @@ important to [set the right tone][writing-tone] when writing messages.
 A JSON representation of an error response might look like the following
 example.
 
-For the purposes of following best practices, it’s helpful to break the
-error response into sections. Note that the order in which you write the
-error message is often different from how the error is presented to
-users.
-
-
 ```json
 {
   "error": {
@@ -130,12 +125,12 @@ descriptions, and examples:
   + A developer-facing error message, which **should** be in English.
     Any user-facing error message **should** be located in the
     LocalizedMessage payload.
-  + *Example message*: \"The zone \'us-east1-a\' does not have enough
+  + *Example message*: `"The zone 'us-east1-a' does not have enough
     resources available to fulfill the request. Try a different zone, or
-    try again later.\"
-+ `details Object (repeated)`
+    try again later."`
++ `repeated google.protobuf.Any details`
   + Additional text details about the error, which includes
-    `ErrorInfo`,`LocalizedMessage`, and so on.
+    `ErrorInfo`, `LocalizedMessage`, and so on.
   + *Example*: Described in the [ErrorDetails](#error-details) section.
 
 #### [ErrorDetails][details]
@@ -192,24 +187,12 @@ descriptions, and examples:
   + Be meaningful enough for a human reader to understand what the
     reason refers to.
   + Be unique and consumable by machine actors for automation.
-  + *Example*:  CPU_AVAILABILITY<br>
-    Distill your error message into its simplest form. For example, the
-    `reason string` could be one of the following text examples in
-    UPPER_SNAKE_CASE: `UNAVAILABLE`, `NO_STOCK`, `CHECKED_OUT`,
-    `AVAILABILITY_ERROR`, if your error message is,
-
-    > The Book, "The Great Gatsby", is unavailable at the Library,
-    > "Garfield East". It is expected to be available again on 2199-05-13.
-
-  + In contrast, using either of the following reasons is not
-    recommended: `THE_BOOK_YOU_WANT_IS_NOT_AVAILABLE`, `ERROR`. And,
-    using either of the following reasons breaches the required
-    formatting and is not allowed: `librariesAreGreat`, `noBooks`.
+  + *Example*:  `CPU_AVAILABILITY`
 + `domain string`
   + The logical grouping to which the `reason` belongs. The error domain
     is typically the registered service name of the tool or product that
     generated the error. The domain must be a globally unique value.
-  + *Example*:<br>`pubsub.googleapis.com`
+  + *Example*: `pubsub.googleapis.com`
 + `metadata map`
   + Additional structured details about this error, which **should**
     provide important context for customers to identify resolution
@@ -348,12 +331,12 @@ descriptions, and examples:
 
 - `description string`
   - Describes what the link offers.
-  - *Example*: "Troubleshooting documentation for STOCKOUT errors"
+  - *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
+    `"https://cloud.google.com/PRODUCT/docs/ERROR-REASON"`
 
 ### Error messages
 
@@ -370,17 +353,16 @@ payload is present in the message.
 If the error message contains ErrorInfo payload (a machine-readable
 identifier):
 
-+ `Status.message` *string* and `LocalizedMessage.message` *string* can
-   change
-+ New metadata fields can be added
++ `Status.message` and `LocalizedMessage.message` **may** change
++ New metadata fields **may** be added
 + However, existing metadata fields **must not** be removed and existing
-  metadata field keys cannot be modified.
+  metadata field keys **must not** be modified.
 
-If the error message does *not* contain ErrorInfo payload (usually for
+If the error message does not contain ErrorInfo payload (usually for
 pre-existing APIs):
 
-+ The `LocalizedMessage.message` *string* can change
-+ However, the `Status.message` *string* **must** not be changed, as
++ The `LocalizedMessage.message` string **may** change
++ However, the `Status.message` *string* **must not** be changed, as
   this change is backward-incompatible.
 
 ##### Message alignment
@@ -502,7 +484,7 @@ data instead.
 
 ## Changelog
 
-+ **2024-01-10**: Incorporate guidance for writing effective messages.
++ **2024-04-02**: Incorporate guidance for writing effective messages.
 + **2023-05-17**: Change the recommended language for `Status.message` to be
   the service's native language rather than English.
 + **2023-05-17**: Specify requirements for changing error messages.