Improve UX in error messages

[ann0see]

While talking to a bunch of people and helping them set up Jamulus, I had the impression that error messages in Jamulus don't always seem to be self-explanatory and lead to a fix. I think some are too long or too technical (especially those coming up with a non-functioning device due to sample rate mismatch see: #1567 and #1564 which are clear examples that the error messages don't seem to be good)

Obviously making them understandable is not an easy task. However, I'd like to start a discussion on making error messages more user friendly and maybe look through the code.

Also see:
https://uxplanet.org/how-to-write-good-error-messages-858e4551cd4

Tagging @gilgongo and @mulyaj here.

[gilgongo]

I was just about to mention this! I think it's because they've been written by people too close to the issues. Some of the English is also a bit off, but that's less of problem.

Would it be possible to gather up all the UI messages in one place and have a look at them?

(also BTW "Before sitting down to write an error message, consider whether the system can be designed such that it isn't needed.")

[ann0see]

Would it be possible to gather up all the UI messages in one place and have a look at them?

Probably. I think they are all wrapped in tr () and can therefore be found in Qt linguist.

There are some messages like "No ASIO audio device (driver) found." or "No usable [...] (driver found)" which should have higher priority (= include in next relase)

[mulyaj]

We can also relate this to the issue about style and tone.

I can brainstorm some guidelines that can be followed for both Jamulus and its site so contributors have a better idea of how/what to write.

[mulyaj]

Here's a draft I've made, feel free to comment on it.

[ann0see]

Yes. That looks good. Probably it will be a living document which can be applied for both the docs and the software. Should this be part of the contributing file if yes: on the website or here?

[ann0see]

First one:

jamulus/windows/sound.cpp

Line 563 in 0d593fc

throw CGenErr ( "<b>" + tr ( "No ASIO audio device (driver) found." ) + "</b><br><br>" +

No ASIO audio device (driver) found. The Jamulus software requires the low latency audio interface ASIO to work properly. This is not a standard Windows audio interface and therefore a special audio driver is required. Either your sound card has a native ASIO driver (which is recommended) or you might want to use alternative drivers like the ASIO4All driver.

Suggestion:

Install an ASIO Driver to use Jamulus

If you own a device with ASIO support, install its official ASIO Driver; if not, you'll need to use a generic one like ASIO4ALL.

We could debate if we want to include something like "To provide low latency audio, Jamulus uses ASIO".

Next one:

jamulus/windows/sound.cpp

Line 149 in 0d593fc

return tr ( "The audio device does not support the "

The audio device does not support the required sample rate. The required sample rate is: SYSTEM_SAMPLE_RATE_HZ Hz.

Suggestion:

The current audio device doesn't support the required sample rate. Please use another device/configuration which supports a sample rate of SYSTEM_SAMPLE_RATE_HZ Hz.

[ann0see]

it implies there are other "generic" ASIO drivers. Are there?

Yes, there are. I think there's even a video on them somewhere on YouTube.

[mulyaj]

These are pretty good! I think to make it even more precise, we'd need to clearly identify the problem. After that we (humbly) offer a solution.

So for the first example, we can keep the first sentence and tweak it a bit:

No audio device with an ASIO driver detected.

To use Jamulus, please install an ASIO Driver.
If you own a device with ASIO support, install its official ASIO Driver; if not, you'll need to use a generic one like ASIO4ALL.

For the second one, would it be possible to replace "The current audio device..." with "Your current audio device"? Also, I'm being a little nitpicky, but watch out for the word "which", as in this case, "that" should be used, since the description of the device/configuration defines the sentence.

[ann0see]

For the second one, would it be possible to replace "The current audio device..." with "Your current audio device"?

Yes, sure!

Another thought on @mulyaj's suggestion: Is "To use Jamulus, please install an ASIO Driver" clear enough that Jamulus will not open?

[mulyaj]

It doesn't explicitly explain what went wrong. It seems fairly easy to imply what happened, but we shouldn't need users to imply the cause of the error.

[ann0see]

Ok. I'll open a PR on this to keep this discussion focused on the general topic of rewriting error messages.

Edit: see #1569

[ann0see]

Opened a new PR for discussion: #1732

[ann0see]

Also linking https://onlineornot.com/what-fastly-outage-can-teach-about-writing-error-messages as reference