Guidelines for Messages in Open 3D Engine

Messages, especially warnings and errors, must provide clear and actionable information. Poorly written messages might confuse and frustrate users, leading to negative user feedback and sentiment. Well written messages lead users to better behaviors and workflows, enable users to report issues more effectively, and build user confidence. Writing effective messages requires more effort, but is very worthwhile.

When developing and debugging features, it’s common to use messages to output data (such as a function’s result) with little additional information. These messages, however, might be encountered by another developer or user in an unexpected context. Useful messages provide contextual information and a path forward where possible, in clear and concise language. An effective and helpful message acknowledges the inconvenience for the user and reassures them with guidance to solve the issue.

Message considerations

Developers often display low-level information, return values, and exceptions in messages that are narrowly scoped to the function or sub-process that generates the message. While these low level messages might be meaningful to developers, O3DE users are almost always focused on some larger task. When crafting messages, answering the following questions can help you determine how to write messages that are useful to users:

• When and where might a user might encounter this message?
• What type of user is most likely encounter this message?
• What might be the user’s task and goal when this message is displayed?
• What type of message is required? Is it a error, warning, informational, or status message?

Suppose, for example, that you are adding a message to a function that processes custom vertex values. Input values in the range of 0.0 to 1.0 are expected. When a value outside of that range is encountered, the value is clamped to the range, and a message is raised. Asking the previous questions about this scenario might result in the following answers:

• A user is processing a mesh that has custom vertex attributes and they might encounter the message in Asset Processor or Scene Settings.
• Creative users (artist and designers) are most likely to encounter this message.
• The user is processing a mesh with custom vertex attributes that are likely intended to be used in a vertex shader, such as a cloth deformer.
• A warning is warranted. The asset can be processed, however the loss of data might not yield the user’s desired result.

The following table assesses some possible messages for this scenario:

The best message provides useful context (vertex stream name, value, asset name, expected range), and a possible solution in as few characters as possible. Determining what critical contextual information can be provided to users can help you write the most broadly useful messages.

Message guidelines

O3DE integrates many third party packages each with their own standards for messages. Passing low level messages, especially those generated by third-party libraries, to a dialog or console is unlikely to help users. You can improve the user’s overall experience by authoring messages that are suitable for broad audiences, including less technical users.

Keep the following guidelines in mind when creating messages:

• Use U.S. English.

• Avoid jargon and idioms.

• Be concise. Use short, complete sentences. Ideally, a error message should be fewer than 200 characters.

• Use simple grammar.

• Use a two sentence standard:

  • Explain the issue in the first sentence as plainly as possible.
  • Offer a solution or link to additional information in the second sentence.

• Use sentence casing. Excessive capitalization might set an aggressive tone.

• Format messages for clarity. White space, commas, and quotation marks can improve readability and comprehension.

• Use passive voice and past tense. For example, use “An error occurred…” rather than “We found an error…”. Active voice, particularly when used for errors and warnings, can be perceived as judgemental and harsh.

• Include critical details when possible. Only include the details that are necessary. Details such as asset names, user defined variable names, values, asset names, entity IDs, component names, and so on, might help users quickly resolve issues for themselves.

• Provide a link to documentation, a PR, an Issue, or source code that can provide more information or a solution.

• Don’t pass low-level messages to the end user.

• Don’t include code in messages. Code takes up space and makes the message harder to scan.

• Write messages with the least technical terminology possible.

  For example, suppose a user encounters an error with the user interface, such as a secondary menu failure. A message like STACKOVERFLOWEXCEPTION: SYSTEM STATE UNKNOWN is technical, cryptic, and alarming. A better message might be ERROR: A stack overflow error occurred when adding the Tool menu to the menu tree. Please report this issue and restart the application.

• Avoid assigning blame in messages. This applies to both users and code, including third-party libraries.

  For example, You supplied a value of type Complex128. Complex128 is not supported by ThirdPartyMath library. blames both the user and a third-party library. A better solution might be A value of an unsupported type (Complex128) was encountered.

• Use an empathetic tone. To help you establish this tone, imagine that you are encountering this error for the first time as a new O3DE user, and ask yourself whether or not you would find this error message clear and helpful, or opaque.

• Request reviews for your messages. Talk to a technical writer, UX designer, user, or another developer to see if your messages can be improved.