Consider renaming VMs for clarity

eloquence commented 5 years ago

The following VM names are potentially problematic:

sd-export-usb: In the UI, we're planning to call export to USB flash drives "Export", and print "Print". If the same VM handles both, it should have a more generic name, like sd-external.
sd-svs: Existing SecureDrop users may be familiar with the abbreviation "SVS". However, the "SVS VM" in the SecureDrop Workstation is emphatically not the direct equivalent of the old Secure Viewing Station. For example, export is handled in its own VM (see above), and additional VMs may be added in future. Since this VM is chiefly responsible for running the client, sd-client may be a more appropriate name.
sd-svs-disp: For similar reasons, we should avoid the term "SVS" here. Simply calling these VMs sd-view or something similar may be preferable. Note that "display" is a more natural expansion of "disp" than "disposable", so the use of "disp" here may also cause confusion and users may start referring to it as the "display VM".

Let's kick these suggested alternatives around a bit; I realize these names would have to be updated in a lot of places.

ninavizz commented 5 years ago

Risking irrelevance requesting this: in whatever renaming we may do, I'd also like to request mixed-case VM names. I know it's not very nerdy, but it is better for legibility/quick-recognition. :)

SD-View-disp · SD-Client · SD-External

zenmonkeykstop commented 5 years ago

Devil's advocate - how much will these names matter to end-users? Will they be exposed to them very much, or will workflows just be like "Open the client, plug in a USB on the labeled port. Now, click Export."

It seems like a failure of the application if less-technically-inclined users have to maintain a mental model of which VM does what.

ninavizz commented 5 years ago

Oyy... that is the existential project question, if there ever was one!

So, like: the user cannot print or export from the Viewing VM, as an example; they have to do it from the Client app. That's a major/common mental model we're breaking from, right there, for security. Likewise, when users do view things in disposable VMs, they need to be mindful to always shut those down to not crash Qubes via memory issues.

When the printer is misbehaving, or when the user needs to interact with a print dialog, that will also need to likely happen in the External VM.

Really, I would really prefer to shield them from all this, too. For the Pilot tho, some things gotta just ship rough, to get a better sense of the value everything else is delivering on... if that makes sense.

ninavizz commented 5 years ago

For when this does get discussed...

Below is my scratchpad list of candidate names, for the print/export VM.

My primary concern inasmuch as usability is concerned, is of an English language name too closely approximating either the concept of printing or of saving. The VM meets both needs, and too closely hearkening one or the other may confuse users. Saying Print/Export conversely, is clear but clumsy.

SD-External is the current front-runner. External is still is a lot of characters to stuff onto a laptop sticker that is co-located to a single port, and to me is still a touch cold/robotic sounding. Cold is more in character w/ SD than Cute or Esoteric though, so in External's favor it's neither of the latter.

I tend to personally bias toward extremes of esoteric or cute, and Erik tends to personally bias toward extremes of technical or generic... however we both want something that is as clear and as human as possible. Memorable would be nice, but w/o calling attention to itself.

Intuitive is not necessarily a goal, as none of this fits existing mental models for most humans. Also, above biases not cited in a negative fashion; just an honest part of problem solving! :)

Runner-ups

SD_Send · SD_Capsule · SD_Hatch · SD_Transfer · SD_ToGo · SD_Between · SD_Transport · SD_Mezzo (may be a definite Nay, Erik didn't seem to wild about)

Definite Nays...

SD_Vestibule (too esoteric) · SD_PrintExport (too much text for a sticker) · SD_Transport (too much text for a sticker) · SD_CleanRoom (too esoteric) · SD_Sanitize (too specific, and incorrect in its allusion) · SD_SafeTake (sounds like a dumb home security thing) · SD_Carrier (too esoteric) · SD_Pigeon (too esoteric—for some people...) · SD_Mudroom (too esoteric) · SD_Between (too esoteric) · SD_Takeout (too food-y)

zenmonkeykstop commented 5 years ago

Another thing to bear in mind is that this will be used by folks for whom English is a second language or not one they speak at all, and that people using the system may not be familiar with terms like "mudroom" - not really a word in common use outside of North America. The VM names will almost certainly not be localized, so terse and technically correct (the @eloquence way) is probably the way to go.

(A sticker on the laptop can be in any language so that's not as critical.)

rmol commented 5 years ago

Continuing from Send/Hatch/Transfer/Transport, how about something near Egress/Exit/Outlet? That would make it clear that this is the path out of our secure confines; is short and sensible for a port sticker; and translates pretty well in at least a few languages (salida, sortie, Ausgang/Austritt?).

I agree that ideally people wouldn't have to think too much about the VM names, but you've got me wondering how much trouble it would be to translate them. :slightly_smiling_face:

zenmonkeykstop commented 5 years ago

Given that folks will be trained to some extent before being let loose on the workstation, could just make the sticker an arrow pointing at the correct port.

rmol commented 5 years ago

:man_facepalming: @zenmonkeykstop, laying the polite smackdown on overengineering. Nice.

ninavizz commented 5 years ago

Context-fail on my part, my bad... <3

@zenmonkeykstop @rmol you both make completely awesome, astute, and relevant points. None of this (to me, at least) is a "Nina's way vs Erik's way" schtick. It's helpful for me to see the feedback you both shared here, tho, to realize that I totally did not frame the exercise appropriately.

SO... stepping-back: what's in a name? Names that resonate are clear and hit the mark, for many reasons—but there are SO MANY words in each language, that it is statistically impossible to attain the most successful names by ideating, evaluating, critiquing, and culling, all in one combined process.

Naming as an exercise in product or branding development, is typically broken-down into 7 phases.

What's the Point? — what is trying to be communicated in the name? Something simple and singular to inform the next generative step; to set the next step in the right direction, more than to restrict its options.
Brainstorming — name all things that "feel right" and record them, without prejudice or hesitation. Just on instinct... pattern-matching with fuzzy-logic in your head around mental models and what "feels" right. Very un-Spock-ish and counter-intuitive to scientific minded processes, but those do happen—just not in the first step. Within this phase, "Mudroom" worked great.
First Edit — then as a team, go through all the brainstormed names and critique why some of them may or may not work. Within this phase, @zenmonkeykstop's feedback on "Mudroom" is perfect...
Establish Evaluative Criteria — from the above exercise, then, formalize rationale that went into the first edit, to establish global evaluative critieria... along with reasons why. Here, @zenmonkeykstop's point on "Mudroom" is then solidified as a MoSCoW'd criteria... or, it's not. This is where it's especially important for a team to be running the exercise, and not just one person.
Rinse, Repeat 1 & 2 against 3 to come-up with a first-pass solution.
Test — Get it in front of users. Via guidance from a trained researcher, observe and ask the right questions to learn a. how important are the damn names to the broader priorities, and b. are these names cutting the mustard. Ad agencies often get things wrong by using focus groups in this step... which is how things like the Pontiac Aztec came to be.
Synthesize findings, Rinse, Repeat 1-4 as few times... then get it in front of users, again.

The best results come when the full team goes all-in on each step, and does the full exercise as a synchronous or asynchronous guided workshop.

@zenmonkeykstop Your shared observations on my mudroom idea perfectly capture why it won't work. But, they're "perfect" because they present a clear objective against which all/any words presented, cannot work.

Unfortunately I muddled things by presenting a list I brainstormed, with a first-pass at editing... but halfassing both steps, and also halfassing how I presented mine and Erik's rationales.

Erik is always going to be the most conservative voice, and I'm always going to be throwing myself up against walls to break them down to be the most generative voice, because our collective efforts are the strongest when we each play those roles as ICs; however both polarities are needed, to come-up with the best solutions. It's not that either of us are incapable of wearing the others' hat, but rather that we're intentionally holding to our domain-expertise's polarities to milk the resulting tension, to find that perfect balance. Likewise, because language is such a fuzzy logic kind of a thing, the results of these exercises are always the strongest, when it's more than 2 people participating.

If you read this far, does the above make sense? I mostly plopped everything I did, above, because I didn't want those notes lost in my mountains of notes. But I plopped them here w/o context.

I'd love it if we could all maybe contribute to steps 0-3 in a bucketed G-Doc... and then perhaps come together for a group workshop to get to that first-pass solution?

ninavizz commented 4 years ago

Notes from discussion with Erik

We should do this asap because of docs-debt incurred with how much longer we wait to do it
This really needs to happen for the pilot—it will be confusing to users to name a VM svs when that is the name of a touchpoint in the old SD ecosystem. Even ed thinks so! :D

sd-viewer » candidate for the disp-vm for viewing things sd-client or sd-primary » for the Client sd-transfer or sd-togo » for Export. Nina punts on sd-export as it seems ripe for confusion to name a VM that when it executes both Export and Print functions.

eloquence commented 4 years ago

So, just following up on this, I would propose the following changes for beta:

sd-svs to sd-client and sd-svs-disp to sd-client-viewer. ("Primary" doesn't make sense to me as it might suggest that this is a VM that the user should "primarily" use, which is emphatically not the case.)
sd-export-usb to sd-external. Because the VM handles both print and export, but also because sd-export-usb is quite the mouthful.

These could be handled as separate PRs.

ninavizz commented 4 years ago

^ "SecureDrop Primary" <—if the user is there to use SecureDrop, how is the client VM not what a majority of users should primarily use?

I'm very much not a fan of "client" as it's so jargon-y, and makes me think of beige machines from the 1990s (when it was a more common term).

Also, "App Viewer" or "Client Viewer"... users won't use that VM to look at the app in, they'll use it to view sent things within—So the referencing back to the client, feels odd. "SD" implies it's all a part of the SD family, and that feels important to keep in mind, to me. Otherwise, why are we bothering with teh SD prefix at all?

ninavizz commented 4 years ago

^ Oops... Nina shuts her mouth now, and invites others to the mix—as the Erik/Nina spincycle could go on forrreeeeevvveeeer (which I trust we'd both delight in, tbh, but we also both want this change!). @emkll @redshiftzero @conorsch @creviera @kushaldas @rmol @zenmonkeykstop @ro and everyone else?

sssoleileraaa commented 4 years ago

I like...

sd-svs to securedrop or sd-client

I too never liked "client" but can't think of anything more accurate. The reason I like securedrop is because it's an obvious entry point to managing accounts, downloading and reading messages from the server, writing responses, a place to decide which file to print, export, or open externally, etc. It is an entry point/ main place to manage securedrop submissions, etc. I'll stop myself before suggesting sd-main

sd-svs-disp to sd-file-viewer

It's accurate.

sd-export-usb to sd-device-manager

I think sd-device-manager indicates that it's a place where devices are attached and can be used.

There are a lot of ideas here so maybe a spreadsheet would be helpful. I also think it would be easier to spot our vms if we renamed sd to securedrop. It's more recognizable and there are other two letter vms that the sd vms blend with sometimes when you've worked too long on qubes.

eloquence commented 4 years ago

Thanks for these great suggestions Allie!

sd-svs to securedrop

+1 from my end to that rename, seems clear.

sd-svs-disp to sd-file-viewer

+1 from my end.

sd-export-usb to sd-device-manager

-1 from my end, this is too focused on the internals of the process and not the purpose of the VM (and could lead a technically interested user to believe that the device manager lives in that VM). I still prefer sd-external for this.

Let's try to close this conversation by 12/9 EOD. We'll bring it up at standup then and see if we have consensus; if not, @redshiftzero can make a final call.

Provided we agree to some renaming, I'll take a stab at the implementation during the current sprint.

sssoleileraaa commented 4 years ago

and curious about people's preferences on using securedrop instead of sd (ignoring the part of the name that follow sd and securedrop in this example):

securedrop
securedrop-file-viewer
securedrop-file-transfer
...

vs

sd-client
sd-file-viewer
sd-file-transfer
...

we could also use a different naming scheme for vms that users typically don't interact with, but are still part of the securedrop workstation

ninavizz commented 4 years ago

I'm concerned that on a VM titled securedrop-addenda1-addenda2 the most important part of the VM's name will get truncated-out, when that name appears in dropdown menus.

I really like your idea of naming the client vm simply SecureDrop though. If we could move away from the developer-preferred norm of all lowercase, to mixed-case for VMs journalists might directly interact with, I'd also prefer that—for findability among the sea of other VMs and templates.

Perhaps:

SecureDrop 
SD-Viewer
SD-Transfer
SD-WhonixConnect

???

eloquence commented 4 years ago

I think we should consider the naming schema for templates as part of this, now that we've introduced a distribution version identifier (buster) to some template names. If we want to keep a template version identifier, I would advocate in favor of a $distribution-$number identifier, to avoid the introduction of natural language words into template names, which may change from release to release, and which may introduce confusion as users attempt to parse what these words mean.

If we add such an identifier consistently, it may also be worth avoiding the use of -template in template names altogether, as no AppVM would have the distribution-version identifier.

eloquence commented 4 years ago

I've put together a spreadsheet for VM naming proposals here: https://docs.google.com/spreadsheets/d/1G1aE6lJD0D6ksIqJuP-8e3iw_1VEzRiUX_zIj41yA8c/edit#gid=0

Some names are easier to change than others. Wherever I put "N/A", the name is defined upstream i.e. not up to us.

The rules of engagement for this document are basically: if you care, make a column for yourself, and express your preferences where you do care. Please only add one suggestion for each VM. Pick the name that makes the most sense to you -- or feel free to just copy someone else's suggestion. (If you have many ideas, feel free to add them here as comments -- but still pick the one that makes the most sense to you in the spreadsheet.)

We'll see if consensus emerges for or against specific changes; if not, @redshiftzero will make the final call as per standard operating procedure. Even if we agree that a specific change would be a good idea in principle, we may decide not to make the change, if it's too much effort for too little gain.

@creviera @ninavizz I've tried to reflect your preferences from comments above, but of course please edit as you see fit.

eloquence commented 4 years ago

If we could move away from the developer-preferred norm of all lowercase, to mixed-case for VMs journalists might directly interact with, I'd also prefer that

We're operating with the following constraints:

Qubes does not permit spaces in VM names;
There are existing service and template VMs on the system that we can't remove or rename, which follow the lower case convention;
We can't (and shouldn't) force removal of existing VMs from the system, which the user will likely set up according to existing Qubes conventions.

Due to these constraints, I see limited utility in using a mixed case convention (SD-FileViewer is only a marginal improvement on sd-file-viewer, IMO), and a high risk of ending up with multiple conventions used across the system, which I think would increase difficulty of navigating and understanding the system.

This is why I've opted against mixed-case proposals in my own suggestions added to the above document.

eloquence commented 4 years ago

We discussed this briefly at standup today and will check in again over the next couple of days. As a reminder, if you do care about this issue, please weigh in with your suggestion(s) on the spreadsheet, or +1 ones which are already there (by copying them into your column):

https://docs.google.com/spreadsheets/d/1G1aE6lJD0D6ksIqJuP-8e3iw_1VEzRiUX_zIj41yA8c/edit#gid=0

Cell comments to explain why you think a specific name makes sense are appreciated :)

rocodes commented 4 years ago

not to complicate things, but I vote for (pretty similar to allie):

securedrop instead of sd-svs
secure-view/ view(er)/sd-view instead of sd-svs-disp
export or export-print instead of sd-export-usb (technically, "external" is more accurate, but it's also more abstract, and Export is an action that is used a lot in computing already, so I think it captures what is happening in a more active way than external does)

eloquence commented 4 years ago

@rocodes Not at all - would you mind adding a column for yourself to the spreadsheet?

https://docs.google.com/spreadsheets/d/1G1aE6lJD0D6ksIqJuP-8e3iw_1VEzRiUX_zIj41yA8c/edit#gid=0

ninavizz commented 4 years ago

Hey gang! I put everyone's ideas together in some mockups, so we can see how all the names work with alphabetization and color options. https://invis.io/CAV9UXNBRTJ#/397881981_Naming_-_Today

eloquence commented 4 years ago

Thanks for putting this together, @ninavizz, it's definitely helpful to see the options visually. I agree that the schema of having all VMs users are meant to interact with start with securedrop-, and the others with sd-, has a certain appeal.

I'm not observing the capitalization behavior ("securedrop -> Securedrop") you describe on the second screen. VM names on the second level of the menu structure are styled exactly the same as on the first (e.g., sd-svs remains sd-svs throughout the menu).

ninavizz commented 4 years ago

You have the most up-to-date Qubes laptop(s), not me—so I'll take your word on this & update mox accordingly! Thx!! :)

eloquence commented 4 years ago

Hi all, thanks for the comments and input. Based on this input, I've put together some concrete proposed naming guidelines and suggested changes.

I'm deliberately not speaking to colors here and will follow up on that separately.

Proposed guidelines

1) A VM's purpose should always be described in a single word. Because we are dealing with prefixes, suffixes, variants, and forced hyphenation, we should avoid multi-word names, as these get unwieldy very quickly. So, sd-maker beats sd-thing-maker, because we might also have sd-maker-debian-10, sd-maker-dvm, or similar variants.

2) We should stay close to Qubes conventions in terms of naming and colors. Examples:

"sd-something" beats "SD-Something" because the Qubes convention is for names to be lower case.
Template naming should be similar to existing local names, e.g., "debian-10" is preferable over "buster".

3) We should make the VM used to run the SecureDrop client application an obvious entrypoint that is easily discoverable by the user. Even if we position a desktop icon as the primary entrypoint, the client app should be easy to locate in the menus.

Problems with a pattern of using "securedrop-" for other user-facing VMs

These is one pattern I think we should reject: use of "securedrop-" to identify other user-facing VMs, (other than the client VM), e.g.: securedrop-export and sd-proxy coexisting in the same scheme. In this naming scheme, securedrop-export has the securedrop- prefix, because of the assumption that users may need to interact with it, while sd-proxy is seen as more system-internal.

The problem with this pattern is that we may get the assumptions wrong, may have to issue renames, and may cause significant confusion of our users when we do ask them to interact with sd- VMs.

Concrete proposal

Based on these guidelines, I would propose the following concrete naming changes:

1) Rename sd-svs to securedrop. This is IMO the most important and the least controversial.

2) Change the substring export-usb to devices. I've previously proposed external, but upon consideration I'm swayed by the argument in the spreadsheet that devices, while technical, wins on precision grounds.

3) Change the substring svs-disp to viewer. While "viewer" is a bit less precise than "file-viewer", this tradeoff is IMO acceptable here to satisfy the "one word" guideline above.

4) If and only if this change is not too arduous, I would also propose that we change the substring "buster" to "debian-10" (which is more consistent with Qubes practices), and generally avoid the suffix "-template" as unnecessary.

The full list of all these proposed name changes is in the "Proposal (Erik)" column in the spreadsheet.

To get us closer to a rough consensus, at this stage I would like to request comments if you have significant disagreements with the proposed guidelines or specific names. Regarding template changes, I'd appreciate more clarity on the technical complexity here -- I also don't want to sign us up for this if it's a major undertaking. :sweat_smile:

ninavizz commented 4 years ago

wrt the different prefixes—that was proposed to facilitate easier discovery in the App menu, not as a schema to articulate to users as a hard-and-fast rule for them to think about (we should never have to articulate schemas to users, on an aside).

I don't feel renames would ever be necessary, if the day arose when sd-proxy would ever need to be accessed by users. Alphabetization when everything has the same prefix, mixes general-use with advanced-use items, in the App menu—and that is my primary objection. Anything we can do to make the Workstation as friction-free as possible for users, I'd like to do... and grouping common things via a securedrop-thing prefix makes sense to me, per that.

eloquence commented 4 years ago

We chatted about this a bit on the phone today -- basically the issue with prefixing some VMs with securedrop- is that our guesses as to what the user needs to interact with may be wrong, and conflicting with other goals:

We're aiming to minimize need to interact with what in this proposal would be called sd-devices, as auto-attachment would be handled for the user, and export/print are on rails as much as possible.
For stuff like Tor restarts, we may want to create shortcuts, so users don't have to interact with VMs directly.
We may change our mind about all of this several times.

For these reasons I don't think we should guess about the use of a securedrop- prefix for some but not all VMs.

I think there's a stronger argument for using securedrop- for all VMs (and securedrop for what's sd-svs), but:

it's a bigger rename operation (and would ideally include changing the developer VM convention as well from sd-dev to securedrop-dev)
it makes all names longer, which for names with suffixes can get unwieldy;
it makes the securedrop VM for the client stand out less in the menu.

Out of conservatism and because the upside doesn't seem that compelling, I am proposing a smaller, more selective rename operation, as outlined above.

eloquence commented 4 years ago

I'm taking these changes through their paces:

Rename sd-svs to securedrop. Change the substring export-usb to devices. Change the substring svs-disp to viewer.

The change from sd-svs to securedrop has at least these downsides:

In technical contexts, there's more ambiguity and the term has to be put in quotes or qualified ("the securedrop VM") all the time. I could see this occasionally crossing into support confusion as well ("shut down the SecureDrop VM" - "which one?").
As Nina noted, it's alphabetized below the sd- VMs which somewhat negates the discoverability benefit.

Because the user will launch SecureDrop through an icon on the desktop, I'm not averse to a technically precise but less friendly term like sd-client for this VM, which is still IMO much better than the confusing/cryptic sd-svs. That said, I'll prepare a PR with the securedrop name so we can all see whether the downsides outweigh the upsides.

conorsch commented 4 years ago

Those are great points, @eloquence. Off the cuff, I'm guessing sd-client will be more useful over time, but happy to review once the PR lands, and go from there.

ninavizz commented 4 years ago

+1 to Conor's assertion that those are great points, Erik.

It sounds, then, like the core finding from your explos is that in the context of discussion and documentation, the sd prefix feels helpful to contextualize that what's being discussed is a VM. Over-use of the phrase securedrop I'll agree is totally confusing, considering it's the name of the core product, the ecosystem, etc.

My only objection to sd-client is that the word "client" is a technical term, when the words "app" and "application" mean the same thing but are far more common and understood. "Clarity" is to me more important, than literal "accuracy," from a communication and comprehension standpoint... and clarity rarely ever needs to compromise in accuracy, but often literal/technical accuracy obfuscates clarity.

We're tentatively naming the client "SecureDrop Desktop," and especially in user-facing documentation I feel it should only ever be called either that, or "the app."

How would y'all feel about sd-desktop as the VM name? This also points back to my earlier push to wanting to name the client... and, especially for this, I'm fine just going with "Desktop." Since it's a Desktop app. Like Signal Desktop.

eloquence commented 4 years ago

How would y'all feel about sd-desktop as the VM name?

This name could give the impression that it's an entrypoint to a "desktop for SecureDrop", as opposed to a single app. I see significant potential for confusion, especially if we don't have time to rename all the current instances of "Client" (which we don't for the beta).

I would favor sd-client or sd-app. I think sd-app is neutral, descriptive and clear, and gives us future-proof flexibility to call the client "SecureDrop", "SecureDrop Client", "SecureDrop Desktop", or "SecureDrop Honey Badger". Thoughts?

ninavizz commented 4 years ago

I'd personally prefer SecureBadger Honey Drop, but agree 100% with your rationale on the sd-app vs sd-desktop; the latter, I'd only included as it was the closes to consensus name we'd come up with for the client.

Thank you all for indulging my desire to shield our end-users from potentially alienating or confusing IT jargon.

freedomofpress / securedrop-workstation