2

I am facing a design problem related to the design of the user notification messages to be used in a web application.

Just for the record, I am working in a JS environment and use a json structure to store user notification messages. However, I think the actual tech stack I use is of no importance here, since this is more of a high level software design problem.

I see two extremes between which I would like to take a middle way:

  1. Highly generic messages which do not offer great detail, but which make the design maintainable, clean, and uncluttered, as well as applicable for a wide variety of situations. As an example, think of creating a new book / user / car / etc. in an app. With this approach, the user notifications could be:
    • on success: "Entity created successfully"
    • on error: "Could not create entity"

VS.

  1. Highly informative and customised messages, but which make the design complex. Following the example above, we would need to have three messages for success and three for error:

    • on success: "Book created successfully" / "User created successfully" / "Car created successfully" / etc.
    • on error: "Could not create book" / "Could not create user" / "Could not create car" / etc.

    Furthermore, if entities are added / changed, new messages need to be added; or, even worse, if the success message for instance is changed, it needs to be changed for every entity (book / user / car / etc.). Adding to this i18n aspects, maintainability becomes problematic.

I could cobble together some JS string interpolation to make the solution a bit more flexible, but I'm not sure that is the best approach.

Of course, the examples are a bit trivial and contrived, but I think they illustrate what I'm trying to express. How can one approach this design problem?

  • How to convey notifications/errors to the user is part of the requirements, not the software design. Therefore, it should be approached from the user's point of view. The use of past tense in your examples reveals you are doing it wrong. – D Drmmr Apr 6 at 13:44
  • You are seriously suggesting to show an end user a message “entity created successfully”? – gnasher729 Apr 7 at 10:03
  • @gnasher729 Do you also have something constructive to add, besides fake outrage? Please read the post -- I said explicitly that these were trivial, made up examples to illustrate my point. – ACEG Apr 8 at 7:41
  • @DDrmmr Like I mentioned in an answer below, I am in a privileged position, in that I can pretty much "write my own requirements", as long as the software does what it's supposed to do. I want to design it "the right way" more for myself, than because it is required by the users, who are my co-workers and for whom this software is just a small helping part of their daily work. – ACEG Apr 8 at 7:53
1

What do you know about the actors of the system? Are they tech-savvy? For tech-savvy users, the word Entity is totally meaningless. Are they even humans? Are they HTTP clients?

As in the real world, messages should be adapted to the interlocutor.

What do the requirements say about these messages? Are they all the same, so that you can implement placeholders or templates?

request.create.resource="${entity} created successfully"

Are they somewhat more specific?

"[User] [X] registered successfully. We sent an email to [email] ...."

if entities are added/changed, new messages need to be added; or, even worse, if the success message, for instance, is changed, it needs to be changed for every entity (book/user/car/etc.). Adding to these i18n aspects, maintainability becomes problematic.

Note that i18n messages are to a lesser or greater degree static resources. Even if they are stored in DB, it takes you to execute scripts for its maintenance.

On the other hand, if you add new entities to the app, adding new messages is part of the evolutive and that's as problematic as simpler is the solution for supporting multilanguage. Don't confuse "complexity" with "laziness".

To my experience, the "best" solution is going to be the one that eases the way you release these resources without rebuilding and redeploying the application. You could dynamically import i18n files from a CDN, DB or from the file system itself. The import might happen in background or foreground. The content can be whatever you need: JSON, CSV, key-value pair, etc. You have to find the implementation that best fits in your deployment pipeline and your stack.

  • I'm in a quite privileged positions as the users are co-workers, so I have quite a high degree of freedom in designing the system as long as it helps them. Thank you for your answer - it's the one that understands my question the best. Especially the last paragraph is in the direction I was looking for, i.e. what aspects to take into account when thinking about and designing the system. – ACEG Apr 8 at 7:46
4

First of all, success and error/failure messages are not symmetric. Success should be signalled clearly but unobtrusively. Normally, removing the spinning cursor that indicates a running operation should be enough.

On the other hand, error messages should convey as much information to the user as is available and helpful to solve the problem. If the issue is with data provided by the user, the message should indicate what was wrong and probably point to documentation about correct usage. In case of server problems, the message should contain info that allows support to pinpoint the problem quickly.

Messages like "Error: entity could not be created" are not helpful to users nor support people.

  • Well, these are of course not the actual messages used -- I just needed something simple to illustrate my example :-) What support / devs see is a different aspect from my question, and is handled with stack traces and other context info stored in logs. – ACEG Apr 4 at 11:33
  • Still, the distinction between success and error messages should be made, and error messages should be detailed and helpful. This does not necessarily lead to a complex design, as you already have the places in your server code where errors are signalled, and these are most likely specific to the entity. – Hans-Martin Mosner Apr 4 at 11:43
-1

For a average consumer sort of application, error messages should simply not happen to begin with. Validation messages are OK (and, of course, need to be customized to the activity at hand). But if the user has entered valid data and done everything else correctly, the application should simply work.

Of course, bad things do occasionally happen. If there is an unexpected problem (e.g. your database server is down), it is not likely there is much an end user can do about it, so there is not much point in providing detailed information.

That being said, there is one thing an end user needs to know: what to do next? So for example it is very useful to tell them if they can try again or who to reach out to for help. With that in mind, some simple error messages may suffice:

There was an error processing your request. Please try again or contact support at 1-800-234-5678.

Or

Oops! Something went wrong. Our engineers have been notified and we will look into it.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.