Improve error messages

[crystalenka]

Several people have sent me or posted in chats this article about writing better error messages.

While the business model of Wix is very different than Joomla (which affects some of their decisions), we could definitely improve upon our error messages and processes surrounding them. It's been on our list for a while; it's time to get it done.

Some truncated quotes pulled from our internal chat to document what our thoughts were and what our process could be:

Obviously the context is different and some of what they did are business decisions for Wix, but the formula for "say what happened, provide reassurance, explain why, and give actionable next steps" seems to be a good one, especially if we can provide more details on what went wrong than we currently do.

I think the model they are using is excellent. Its far too easy in Joomla to create a text definition and then use it / translate it and a lot of the language used is developer speak for developers understanding.

Can we have different error messages based on the context of the error? Is that technically possible?

all (most) error messages are language strings (reusing the same again and again) so yes, we could set specific ones (probably create an error.ini with all containing them...)

Goals from this project

1. Documented error message best practices, with examples and templates to follow when new error messages are added. This documentation should go into the developers manual that's currently in progress.
2. A new error.ini language file that will have all the revised error messages used in core. (Q: would this need to be different in front end and back end?)
3. Process to review new error messages and ensure they are continuing to follow new best practices/defined templates.

Next Steps

Everyone seems to be in agreement that this needs to happen; the challenge is identifying all the different contexts that errors are called from and really documenting why it happens and how to communicate it best to the user.

We need someone to create a list of language strings for errors as they currently exist in Joomla, documenting the string, the EN-GB value, and the file where they are currently located.

I will create a google sheet to store these so we can keep track; once we have an idea of the different language strings, we will need to collaborate with some developers to document under what circumstances these error messages are shown.

To do

• Create Google sheet to track error-related language strings
• Document error language strings in above spreadsheet
• Document template and best practices for our new language strings
• Define the context(s) surrounding each error message as it exists now
• Define common strings or string parts (for example, are there only a few options for titles, or for next steps? Would we be able to make it so there are "parent" strings where the more detailed error is passed in? Or do we need to have unique strings for every error?)
• Create new language strings in google sheet where necessary to address new contexts
• Work with developers to deprecate old language strings/processes and include new ones in new error.ini files - is this a major B/C break? J5 or J6?

More thoughts TBD