Copy edits to Terarium error messages easier to understand. Below are some suggestions for adding to and maintaining these going forward.
General tips
Use informal conversational language wherever possible.
Use contractions ("can't" instead of "cannot").
Use active voice instead of passive (instead of "the service was terminated…" try "We terminated the service…").
Avoid software development jargon that users may not understand ("UUID," "curies").
Don't introduce backend terms that users never see in the UI. For example, avoid terms like "artifacts" and "assets" if users only see "resources" in the UI.
Consider whether it's necessary to name a backend service that users never see. Instead of referencing "SKEMA," determine whether it would be clearer to refer to our "model service."
Terms
Curie
Not typically familiar to an end user. Replace with "ID" or "unique ID."
Error
Avoid negative terms. Simply state the results of the error. Instead of "An error occurred while trying to set project permissions…" try "We couldn't set project permissions…"
Fail
Avoid negative terms. Simply state the results of the failure. Instead of "the service failed to perform the task…" try "the service couldn't perform the task…"
Please
Only use "please" when we're asking the user to take an action as a result of a system error. If the error is a result of a user action (for example, trying to upload a file that's too big), state the corrective action without saying "please."
Provide
Avoid this verb when describing user actions. Be more descriptive about the action that triggered the error message, such as "selected" or "entered."
Return
Avoid this verb when describing search results or application outputs. Instead of "Our service didn't return any results…" try "Our service didn't find any results."
Request
Avoid this verb when describing user actions. Be more descriptive about the action that triggered the error message, such as "selected" or "entered."
Supply
Avoid this verb when describing user actions. Be more descriptive about the action that triggered the error message, such as "selected" or "entered."
Terarium
Don't repeat the name of the application in error messages; users know what tool they're using. Replace with first person plural (instead of "Terarium's model service is unavailable" try "Our model service is unavailable.")
Unable
Instead of saying we "were unable to…," simply state "we couldn't…"
UUID
Not typically familiar to an end user. Replace with "ID" or "unique ID."
Copy edits to Terarium error messages easier to understand. Below are some suggestions for adding to and maintaining these going forward.
General tips
Terms