Provide a more detailed error message than "No known servers"

[aaronraimist]

This PR attempts to give the user some more information about what went wrong when they try to join a room through a unroutable Room ID. This is attempting to improve the situation around https://github.com/vector-im/element-web/issues/2925.

Fixes https://github.com/vector-im/element-web/issues/13247

This will definitely need some design help with the wording.

Before	After

---

Here's what your changelog entry will look like:

✨ Features

• Provide a more detailed error message than "No known servers" (#6048). Fixes vector-im/element-web#13247. Contributed by @aaronraimist.

[SimonBrandner]

@aaronraimist, could you please include a screenshot?

[aaronraimist]

Sure.

Before:

After:

[niquewoodhouse]

Took a look at this and I probably need some help to know if this suggestion make sense/is actually true as a lot of the terms I just guessed what they might mean in reality to people. I found saying things like RoomId a bit hard, having to explain what they are, and also what internal means etc, so just went generic but basic. I do reference an address as I think that's what the UI refers to.

• You didn't join the room
• You can't join with that link. The room might be missing some details (like an address) that are needed to create a working link. Ask whoever gave you the link to look for an invite or share link option.

[aaronraimist]

The room might be missing some details (like an address) that are needed to create a working link.

@niquewoodhouse The room isn't missing details, the link is missing details

[niquewoodhouse]

The room might be missing some details (like an address) that are needed to create a working link.

@niquewoodhouse The room isn't missing details, the link is missing details

I thought we couldn't tell from the link if the room is missing details? So it might be missing an address. I used my browser to go through some rooms and copy the URL and ones without a room address had a random ID and ones with an address had a real link. So I thought it would be likely that the room's without an address are the ones that people are likely sharing this way (with a room id). Does that sound wrong? Thanks for any help.

[aaronraimist]

@niquewoodhouse room addresses are not required to be able to join a room, but they are the most understandable way to join a room and are the way that most people should join rooms.

Here are the ways that you can join a room with some kind of link:

1. Using a room address (alias)

Someone creates a room and adds a room address like #matrix-docker-ansible-deploy:devture.com. Users on any server can then join #matrix-docker-ansible-deploy:devture.com because that address contains all the information needed to join the room. The devture.com part gives you a server that you can communicate with to get information about the room and the #matrix-docker-ansible-deploy part uniquely identifies that room (on that server).

2. Using a Room ID

Room IDs are random identifiers that are currently formatted like !cNSQwPqhHKkIZdBnvt:devture.com. These appear to have a domain at the end of them but that domain is just to ensure that the entire ID is unique. MANY people see a domain in there and assume these are things that you can use to join rooms but except for edge cases these CANNOT be used to join a room. In the future room IDs will likely be formatted more like !Sr_Vj3FIqyQ2WjJ9fWpUXRdz6fX4oFAjKrDmu198PnI (https://github.com/matrix-org/matrix-doc/pull/1228) which will make this less confusing.

The only time when you can join a new room using only a Room ID is when your server already participates in that room. For example if @bob:server is in room !Bchwqj2mn:matrix.org then @alice:server can also join !Bchwqj2mn:matrix.org. But @steve:a-different-server CANNOT EVER join the room using !Bchwqj2mn:matrix.org because the room ID alone doesn't provide enough information to be able to find the room and join it. @steve:a-different-server currently gets the error message:

This is where this PR is trying to improve the error message.

3. Using a Room ID with a list of servers to join through

In this link https://matrix.to/#/!CWLUCoEWXSFyTCOtfL:matrix.org?via=sw1v.org&via=matrix.org&via=chat.weho.st a room ID is provided, as well as a list of servers that are known to be in the room (at least at the time the user created the link). This link is suggesting that your server communicate with either sw1v.org, matrix.org, or chat.weho.st when attempting to join !CWLUCoEWXSFyTCOtfL:matrix.org. This is the only way you can reliably join a room using a Room ID.

[aaronraimist]

(you'll have to add back the design review request because github)

[HarHarLinks]

I suggest that terms like "Room ID" and "(Room) Alias" have an example (#room-alias:server.tld, !0123456789abcdef) attached to clarify what that text that was pasted should look like.

You might also want to have a non-tech user friendly explanation first ("your link is invalid, try using an alias") and then a more technical explanation in a second paragraph, or toggleable (think <details>) "advanced" section.

[aaronraimist]

Thanks for the suggestion. Once I added those identifiers it looked quite visually busy even with just two paragraphs so I went ahead with the suggestion to use <details>. I took the opportunity to add more information about the limitations of room IDs.

Design: Feel free to tweak wording. It could be reverted back to a simpler explanation but I think this more detailed explanation is fine since it will be hidden by default.

Before	After

[HarHarLinks]

I like this. Some more comments:

• You explain the concept of "via" servers and that none was given, however how to actually provide one is left open. Would it not make sense to hint at matrix.to with via servers?
• I think that generally in the whole app, it is appropriate to format any room ID or alias using the monospaced font with serifs so it is easy for users to distinguish symbols such as l, I, and |. Maybe the design team can incorporate this suggestion into their process.
• (I disagree with the part where a room ID containing a server won't even be tried with the server in the ID, despite implying that info even though it's not guaranteed.)

[aaronraimist]

1. Yes that would be fine. I couldn't figure out good wording for that and I was also fine with the general take away being don't use room IDs, use aliases. If you have suggested wording let me know.
2. Agree. I will make that change.
3. https://github.com/matrix-org/matrix-spec/issues would be the place to raise that.

[gaelledel]

From a UX writing perspective, It is preferable to use short and concise sentences to explain the problem. We should avoid using technical terms that might not be understood by all users. If necessary we can explain these terms but in a short and brief manner.
We should also aim to provide clear guidance on what the user can do to remediate to the problem if there are solutions available.

If we need to provide a step by step guide on how to fix the issue, I would recommend adding hyperlinks in the error message leading to the element.io website. The guide should be fully explained there rather than on the error message modal in the UI

[gaelledel]

@daniellekirkwood Would you be able to help us craft a more suitable error message considering the UX writing principles described above? We can link to https://element.io/help for more guidance if required. Thank you

[t3chguy]

Linking to element.io might be problematic as those links might not work for corporate users with whitelabelled Element instances.

[Johennes]

It looks like we took quite a detour here over the past one and a half years. In favor of our own time, I'd suggest we don't start crafting the copy for this dialog from scratch. Instead lets merge the original proposal shown in the screenshots at the very top of this page. This may not be just the best possible copy but it very clearly is much better than what we have today. Our product and design team can follow up with another improvement separately if they want to.

@aaronraimist are you up for restoring the original diff?

[aaronraimist]

@Johennes Sounds good. I've gone back to the original wording, except for one minor change. Originally I wrote "room alias" but Element calls them room addresses now so I've matched that wording. Here is a new screenshot:

Before	After

Thanks @HarHarLinks and @MadLittleMods for the suggestions and sorry for the delay in adding them. Once this basic improvement is merged either of you can feel free to open another PR with further improvements.

[florianduros]

@aaronraimist I'll add the missing tests to make it pass the quality gate, thank for your work on this PR.

[aaronraimist]

@florianduros thank you!