What are some creative ways to 'document' UI error messages that are manageable and maintainable for developer handover?

Question

Background

I am a designer working for a large organisation that has thousands of system error codes that are associated with system default error messages.

Sometimes these system default error messages do not fit the UI context in which is used, so we have to adjust these messages with something custom to fit its page context per project.

Approach taken

The approach taken for this was to work with a Business Analyst (BA) to populate an excel spreadsheet with

• thousands of error codes with default messages and
• custom messages per the context of usage and
• URL links to designs that contain placeholder text.

Challenge

The challenge is retaining the consistency of error message usage, document maintainability and developer handover.

The way error messages are being documented is the best we have come up with at the moment and wonder if other UX designers have found a better approach to documenting complex error messages for developer handover.

Are there any creative ways or tooling to handle something like this?

Answer 1

One would be categorizing them based on the nature of the error(are you sure you want to ), user actions needed. Based on this you can come up with a common message format for each category.

Maintaining them in excel so it's easier to manage by more copy focused people in the team like UX writers. Seeing them all together on a single screen would help retain consistency. Thereafter syncing them up in your designs can be done with a plugin.

Answer 2

Having all possible error messages documented in a list format is a great first step. These would help to formalize some principles for new and existing error messages such as - do not address users in the second person, provide a short error message supplemented with a remedial action.

Another way to unify the error messages would be to define a set of error state illustrations with one-to-many mappings to the different system error messages.