MSC4161: Crypto terminology for non-technical users #4161
Conversation
uhoreg
added
e2e
proposal
turt2live
added
the
needs-implementation
Co-authored-by: Richard van der Hoff <[email protected]>
Co-authored-by: Richard van der Hoff <[email protected]>
…es to use Alice and Bob
| @@ -0,0 +1,451 @@ | |||
| # MSC4161: Crypto terminology for non-technical users | |||
There was a problem hiding this comment.
Let me start with the positive note - I believe that, at this stage in Matrix evolution, this initiative is very worth while. I think that we need to unify and clean up the language used throughout Matrix, and that is not specific to the cryptography part. That being said, I think we have to answer a fundamental question before we go for this.
This is one of the first, if not the first, MSC that entirely focuses on recommendations to user interfaces and user experience rather than APIs and call flows. If we are to enter the UI/UX guidelines territory, I would prefer that we first agree whether the SCT remit and capability extends there, and how far. A few comments below have what I think needs further discussion. TL;DR (but please respond under specific comments):
- Mainly to SCT: can we make sure this MSC does not end up a single shot and establish a way to further contribute in the same direction?
- Mainly to SCT: if (1) is positive then we may have to do something about our expertise on the subject. I don't think we have enough of it onboard.
- To the MSC authors: external references?
- To the MSC authors and for an eventual spec PR: can we separate the glossary from the phrasebook and treat them differently? The glossary has much higher inertia among users while the phrasebook can be altered and extended faster without consequences for the ecosystem.
There was a problem hiding this comment.
I don't see this MSC as a comprehensive document really covering the ground - and that's fine. I don't believe we should even focus on cryptography, it's just one of more technically advanced areas where we ended up exposing too much of protocol internals to the users. I'm totally happy to start with this but I don't want this MSC to be the start and the end. It would be great to see more effort, from the entire community, on improving UX in Matrix for different user categories. It would be disappointing if this MSC becomes a lonely shot in the direction of UI/UX guidelines.
I don't have a clear path but I know it should be more than an appendix, linked to from the CS API spec. We'll probably have to do some advocacy to raise awareness; we'll also need to think about i18n and l10n to extend good wording to other languages than English (we have prior experience on that!); probably there are more areas. I recognise that everybody signals ENOTIME at this point of reading but I don't see the point in going further with this MSC if we don't treat it as a part of something bigger.
There was a problem hiding this comment.
I'm not sure we at SCT have experience and expertise on the subject. Being one of those covering the clients domain area, I may have to go for some research and self-education before I can responsibly make decisions on this. And/or we might have to call someone in who has appropriate background. Fortunately, Matrix is used by some UI-conscious communities (GNOME, in particular) so we might not need to search too far away.
This is especially critical given how much bike-shedding this subject may cause - particularly around the words and phrases shown in the UI.
There was a problem hiding this comment.
Speaking of this MSC: I would appreciate having more external references. So far the MSC looks like a result of the original research breaking new ground, with minimal prior art. There's probably just a couple of places where other platforms are mentioned, and there are no references to decentralised platforms like E-mail or Web (GMail is not decentralised). It would be great to make sure at least some research has been done if we are to officially endorse specific terms.
For example: next to others, I'm not a fan of "devices", I really believe it's a misnomer we borrowed from centralised mobile-first platforms. I can still grudgingly accept it if we couldn't find a better alternative. But the only discussed alternative was "session", which I agree is (even) weaker. I was surprised that "clients" (taken from e-mail), or "applications/apps" (desktop and mobile environments) are not even namechecked.
Or consider "identity" - I don't know if it's good or bad because I don't see the research behind the choice. I only know it's difficult to translate it to Russian and a few other Slavic languages and, separately, that it confused me when I stumbled on "the identity has changed" wording in WhatsApp. Maybe there's something better, maybe there isn't - it's not clear from the MSC.
There was a problem hiding this comment.
We can adjust phrases but the fundamental vocabulary is not something we can "iterate" easily on; once end users (especially non-technical) get used to it, they won't appreciate changes if/when we discover that something doesn't really work. I would suggest that we actually spec the glossary, leaving specific phrases to a lighter "implementation guide" kind of a document. The implication here is that the glossary is something we actively promote as the standard way to express things in Matrix (and tbh I would really consider it being universal, without "technical/non-technical" separation), while the phrases would be a sort of reference for client authors that we can change quicker, probably without MSCs.
There was a problem hiding this comment.
Speaking of this MSC: I would appreciate having more external references
...
Or consider "identity" - I don't know if it's good or bad because I don't see the research behind the choice...
This is a very good point. I have attempted to provide some external references in 38e2f25 - if you like the general style of this I can try to do it for some other words.
In some cases I think what we are doing in the MSC is just standardising words that are already in use, so maybe the references should rather be to existing Matrix clients - what do you think?
There was a problem hiding this comment.
I would suggest that we actually spec the glossary, leaving specific phrases to a lighter "implementation guide" kind of a document.
We could definitely do a split like this if there is support for it. So far I have thought of what we are doing as a glossary, with the words in bold as normative, and the additional words used for explanation of the glossary, not necessarily an implementation guide. So I am not yet personally convinced that we need a split, but maybe we could make it clearer that the examples are for explanation purposes?
There was a problem hiding this comment.
I'm not sure we at SCT have experience and expertise on the subject. Being one of those covering the clients domain area, I may have to go for some research and self-education before I can responsibly make decisions on this. And/or we might have to call someone in who has appropriate background. Fortunately, Matrix is used by some UI-conscious communities (GNOME, in particular) so we might not need to search too far away.
I'd certainly welcome input from people with other expertise - this is so far mainly constructed from observing words already in use in multiple Matrix clients, and with expert input from product management and design professionals within Element. We have made adjustments based on input from other clients and community members too, but have not managed to get a huge amount of engagement.
However, I'd be keen not to add an impossible barrier to this MSC. Even if it needs improvements later (which I agree could be painful) I think it can improve the lives of users soon after it is merged, and if it is never merged we will never see those improvements.
There was a problem hiding this comment.
1. Mainly to SCT: can we make sure this MSC does not end up a single shot and establish a way to further contribute in the same direction?
I believe MSC4270 is an attempt to address this comment by establishing a context within which this MSC can be applied.
There was a problem hiding this comment.
For example: next to others, I'm not a fan of "devices", I really believe it's a misnomer we borrowed from centralised mobile-first platforms. I can still grudgingly accept it if we couldn't find a better alternative. But the only discussed alternative was "session", which I agree is (even) weaker. I was surprised that "clients" (taken from e-mail), or "applications/apps" (desktop and mobile environments) are not even namechecked.
Thanks, I added more alternatives in fa893e1 . I personally don't think there are better words than "device", but we can try! btw I'm not sure how "devices" is related to being centralised? (I do see how it's from mobile-first platforms, and I think we should embrace that a little since it is how so many people engage with messaging.)
proposals/4161-crypto-terminology.md
Outdated
| Where concepts and terms exactly match existing terms in the Matrix spec, we | ||
| propose changing the spec to use the terms from this document. Where they do not | ||
| match, we are very comfortable with different words being used in the spec, | ||
| given it is a highly technical document, as opposed to a client user interface. |
There was a problem hiding this comment.
I believe it makes total sense to see harmonised but different vocabularies in the API specifications and UI guidelines. In case of UI I would suggest providing some acceptable alternatives to primary key words, as well as known-bad options (this MSC already has those in a few places). Having these helps translators a lot to find the best equivalent in other languages.
|
|
||
| Clients may, of course, choose to use different language. Some clients may | ||
| deliberately choose to use more technical language, to suit the profiles of | ||
| their users. This document is aimed at clients targeting non-technical users. |
There was a problem hiding this comment.
I'm not sure that the proposed language is actually aimed solely at non-technical users. I'm sure it will bring better Matrix experience to technical users who haven't seen the protocol specifications, just as well.
There was a problem hiding this comment.
I agree, but I want to make sure the scope of this document is as clear as possible, to avoid unnecessary debate about issues that are more technical than the issues addressed here.
proposals/4161-crypto-terminology.md
Outdated
| the parts of this section relating to insecure devices should be considered | ||
| non-normative. | ||
|
|
||
| Instances of a client are called 'devices' (not 'sessions'). Aligned with |
There was a problem hiding this comment.
It's worth noting that Element-Web does not follow this advice today: the list of active devices are visible on the "Sessions" tab:
MAS talks about sessions too:
Note "3 active sessions".
There was a problem hiding this comment.
There's a thing that's been bugging me about this. Are "devices" and "sessions" even the same thing? MAS is primarily talking about server-side sessions which correspond to access tokens. But when we are talking about cryptography, we don't mean that but something which is exclusively client-side and corresponds to cryptographic key material.
Sure, there is often a correspondence between the two, but they are not the same thing. They are not even necessarily 1-to-1 given there are client instances which have no cryptography enabled.
So is the terminology problem partly caused by our stumbling over this difference without realising it?
There was a problem hiding this comment.
Updated in 00993d9 to allow either device or session. It's clear that there is no consensus in the community about which word to use, so we take the slight hit of having 2 words, but we avoid clients having to diverge from this proposal.
As for @dkasak 's comments: I think there might be something very helpful there, but I think it's too low-level for this proposal.
There was a problem hiding this comment.
@andybalaam Do you have any suggestions where else we can take it? It's a bit of a fear of mine that the wording used in this MSC, should it get accepted, will interfere with the established technical wording in the spec. Both this MSC and the spec talk about "devices", but they really mean (related but ultimately) different things, don't they?
There was a problem hiding this comment.
I actually think devices here are quite close to what the spec means when it says devices. Where do you see a difference?
In general, I'm not sure where we should take your comments. If you want to propose a change to the wording used in the main spec, I suppose a separate MSC would be the best way.
proposals/4161-crypto-terminology.md
Outdated
| the parts of this section relating to insecure devices should be considered | ||
| non-normative. | ||
|
|
||
| Instances of a client are called 'devices' (not 'sessions'). Aligned with |
There was a problem hiding this comment.
A question that arose in discussion with the SCT: do we actually need to specify "sessions" vs "devices"? Maybe this is something that we can leave up to individual clients, and users will figure it out?
There was a problem hiding this comment.
from earlier discussion with some of the SCT: we can probably just shorten this to something like:
| Instances of a client are called 'devices' (not 'sessions'). Aligned with | |
| Instances of a client are preferably called 'devices' (or 'sessions' as a second choice). Aligned with |
The spec would then use devices.
There was a problem hiding this comment.
I updated this MSC here 00993d9 with similar language to the above, with a slightly more even-handed wording. Given the strength of feeling on this issue I don't want to describe 'sessions' as a second choice, but rather an alternative.
There was a problem hiding this comment.
Thanks for your continued work on this MSC! It's shaping up to be extremely well written, and may be possible to include verbatim in the spec itself (when we get there).
This review is a bit large because it contains primarily editorial considerations, but within there is a suggestion to skip the device vs session debate by allowing both, and preferring device. Ultimately, compared to the other terms in this proposal, I don't feel the difference in terminology would measurably add confusion for users. Provided of course that someone doesn't start calling them "apps" or "connections".
proposals/4161-crypto-terminology.md
Outdated
| the parts of this section relating to insecure devices should be considered | ||
| non-normative. | ||
|
|
||
| Instances of a client are called 'devices' (not 'sessions'). Aligned with |
There was a problem hiding this comment.
from earlier discussion with some of the SCT: we can probably just shorten this to something like:
| Instances of a client are called 'devices' (not 'sessions'). Aligned with | |
| Instances of a client are preferably called 'devices' (or 'sessions' as a second choice). Aligned with |
The spec would then use devices.
| > "Allow key storage" | ||
|
|
||
| > "Key storage holds the keys that allow you to read your message history." | ||
|
|
||
| > "Message history is unavailable because key storage is disabled." |
There was a problem hiding this comment.
For the MSC to consider: it may be alarming to users that keys aren't stored by default? Adding the context that they are stored securely server-side may help ensure that people make an informed decision to turn this on or off.
There was a problem hiding this comment.
I'm not yet sure what you are suggesting. Possibilities:
- Because it may be alarming that keys aren't stored by default: we should rename key storage to "server key storage" or similar to make it easier to understand that keys are already stored locally
- Because we want to encourage users that turning on key storage is safe: we should refer to key storage as "secure"
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Co-authored-by: Travis Ralston <[email protected]>
Based on real-world feedback from Element clients, 'identity was changed', and especially 'identity appears to have been changed' were very confusing. Resetting an identity is something that the user can do themselves, so it is much clearer what we mean. They can ask the other user "did you reset your identity?" and it is easier for them to answer.
Rendered
Conflict of Interest declaration: I am employed by Element. This MSC was written as part of my work on the Element Cryptography team.