Write and finalize supported user stories for the Tor VPN

User stories are short, one-sentence descriptions of a persona and their behavior used to help inform the features an application should support. User stories should be evidence-driven, based upon a combination of user research, the previous real-world experience of the team, and opportunities for innovation in the VPN market as indicated by the competitor analysis.

This ticket relates to the following objective:

• O1.1: Conduct interviews and surveys with target users to create user stories

assigned to @donuts

added UX Team Next Sponsor 101 Research UX labels

assigned to @duncan

changed the description

mentioned in issue tpo/ux/research#68 (moved)

marked this issue as related to tpo/ux/design#35 (moved)

marked this issue as related to tpo/ux/research#56 (closed)

removed the relation with tpo/ux/research#56 (closed)

marked this issue as related to tpo/ux/research#68 (moved)

added S101-O1 label

added Doing label and removed Next label

marked this issue as related to tpo/ux/research#70 (closed)

added Q3 label

added Q2 label

removed Q3 label

mentioned in issue tpo/ux/research#47 (closed)

The UX Team have been consuming a lot of information from many different sources, including

• The literature review: tpo/ux/research#63 (closed)
• The Tor Browser features spreadsheet: Google sheet
• The discovery survey: tpo/ux/research#50 (closed)
• Our existing user research: /user-research/reports/
• The ecosystem evaluation: tpo/ux/research#64 (closed)
• The threat modeling committee
• Conversations in other committees that are ongoing

In February, we began consolidating some of the ideas that have emerged from these activities into non-empirical job stories, and presented the first draft to the wider VPN working group for review:

• VPN UX planning board: Figma link

What on earth are non-empirical job stories?

Job stories are just user stories in a slightly different format. Traditionally, user stories document use-cases like so:

As a [persona], I want to do [action], so that I can [expected outcome]

In contrast, job stories do away with the persona to focus on the situation the user finds themselves in, i.e.:

When [situation] happens, I want to [motivation], so that I can [expected outcome]

And that’s it. This is not to say that we won’t create personas later – but we’d like to avoid sorting our users into neat buckets too early, and focus on their more granular user needs in the short-term instead.

We're calling the first draft "non-empirical” to emphasize that they’re still full of assumptions, that scrappy ideas are still welcome, and that we’ll test those that require validation in the near future. In reality however, they’re quasi-empirical – given many of them are based on existing knowledge, user research and observations.

Lastly, these stories have been sorted into color-coded epics (i.e. themes) for ease of reading and organization.

What comes next?

We need to apply the feedback collected during the review period and break the list of job stories down into two groups:

• Features that are a given for the MVP (a good example being “UI to turn it off and on again")
• Features we need feedback from end-users to gauge their demand and prioritization

That second category is obviously broad, including anything from “we’re not sure if this should be in the MVP or a later release” to “how about this wild idea I had”. Regardless, everything in this category will require some degree of validation.

To do so, we plan on selecting a diverse group of ~10 participants from the call for participation and screening survey conducted in tpo/ux/research#70 (closed) for qualitative interviews – and incorporate questions about these use-cases and prospective features into the interview script.

However we likely won’t get answers to all of our questions from those alone. As such we’re also considering running a second follow-up survey to provide some quantitative feedback, and are currently experimenting with remote card-sorting exercises in LimeSurvey to asses their suitability for this study in tpo/ux/research#56 (closed).

And what comes after that?

Following internal feedback, user interviews and potential second survey we’ll produce a final set of user stories sorted by:

• Intended release (i.e. MVP, Next, Backlog and Icebox)
• Product (i.e. VPN vs browser)

These will be used to inform the product requirements in tpo/ux/research#66 (moved), and wireframes and user journeys in tpo/ux/design#35 (moved). However we’ll likely get a head-start on the wireframes based on the “given” MVP features in the meantime.

Here's a record of the current job stories following internal feedback, ordered by their approximate MVP status:

View the first iteration

Privacy & Security

Feature	When...	I want to...	So I can...	MVP?
Killswitch	my connection to Tor drops out	immediately block all traffic from my device, with the option to override if desired	avoid compromosing my privacy by allowing apps to fallback to a regular Internet connection	Research
Route all traffic over Tor	apps on my device send traffic over the Internet	easily require all traffic from my device to go over Tor	ensure my privacy isn’t compromised by traffic being sent in the clear	Yes
Quickstart	I restart my device	connect to Tor automatically	browse safely in the event that I forget to connect, or traffic is sent from my device before I can do so manually	Research
New Identity	I am browsing a website that may not respect my privacy	clear my browsing history, cache and reload my tor circuits	prevent my subsequent browsing activity from being linkable to what I was doing before	Research
VPN blocking	an app I’m using is attempting to route my connection through another VPN	be given the option to block this connection	prevent that vpn from logging my activity	Research
Proxy bypass prevention	an app is set to be routed through Tor	prevent any traffic leaking in the clear	preserve my privacy and anonymity	Yes
Security settings	I’m reviewing the settings I have applied within the Tor app	see predetermined options for security and privacy	select the settings that best fit my threat model without needing to understand each option individually	Research
Unsafe app warnings	I’m routing an app through Tor that may compromise my privacy or security	be made aware about the risks of using the app	make an informed decision about whether to proceed, and moderate my behavior accordingly	Research
Turn off network before bootstrapping	I launch the Tor app but haven’t connected yet	prevent Tor from making any connections	ensure my configuration is correct before I attempt to connect	Yes
Application isolation	I’m routing multiple apps through Tor at the same time	ensure that each app uses different circuit	prevent my activity from one app being linked to another	Yes
Prevent DNS leaks	a service on my device performs a DNS lookup	route all of my DNS requests through Tor	prevent my IP address getting leaked to my local network	Yes
App containers	I’m performing more than one distinct activity within an app that supports multiple profiles	containerize these activities	prevent the service linking the activity between each profile	Research

Censorship Circumvention

Feature	When...	I want to...	So I can...	MVP?
Connection Assist	I can’t connect to Tor due to censorship	detect and circumvent censorship automatically	connect to Tor and overcome further censorship without needing to configure my connection manually	Yes
Manual configuration	I can’t connect to Tor due to censorship and don’t want to provide my location	be able to manually configure my connection	connect to Tor using custom connection settings, and without providing my location	Yes
Built-in bridges	I can’t connect to Tor due to censorship and I’ve chosen to manually configure my connection	be able to select from a list of bridges	connect to Tor and circumvent censorship	Yes
Request a Bridge	I can’t connect to Tor due to censorship and built-in bridges don’t work	be able to request a bridge	connect to Tor and circumvent censorship without needing to rely on built-in bridges	Yes
Get bridges	I can’t connect to Tor due to censorship and neither built-in nor requesting a bridge works	be able to find alternative bridge lines that are more likely to succeed	provide a bridge manually	Yes
Add a bridge line	I’ve been provided with a bridge line in text format	be able to enter the text string in the Tor app manually	connect to Tor and circumvent censorship using the bridge line I’ve been provided with	Yes
Scan a bridge’s QR code	I’ve been provided with a QR code for a bridge	be able to scan the QR code within the Tor app	connect to Tor and circumvent censorship using the bridge line I’ve been provided with	Yes
Sharing bridge lines	Tor is blocked in my location, but I’ve managed to connect via a working bridge	be able to share that bridge with my peers	help them circumvent censorship and connect to Tor	Yes
Per-app permissions (blocked)	only certain apps are blocked in my location	be able to choose which apps I do and don’t route over Tor	unblock certain apps without slowing my connection or running into issues with others	Yes
No cost	the Internet is blocked in my location	find a circumvention tool that doesn’t charge or feature data caps	access the free and open internet without incurring further costs	Yes

Good usability

Feature	When...	I want to...	So I can...	MVP?
Circuit Display	I’m connected to Tor	see the circuit each app is being routed through	view each relay’s IP address and location	Yes
Exit node selection	services automatically localize their content based on my IP	select the country my exit node is located in	appear as though I’m based in that country	Research
Bootstrapping	the Tor app is in the process of connecting to Tor	see its progress as it connects	know that it’s working and hasn’t stalled	Yes
Automatic updates	an update is available for the Tor app	be notified immediately within the app	ensure I’m using the most secure and up to date version	TBC
Release notes	I’ve installed a new update	read a changelog within the Tor app	get up to date with bug fixes and changes	Yes
Per-app permissions (slow)	an app or service blocks or is too slow over Tor	exempt that app’s traffic from being routed through Tor	use that app without needing to turn Tor routing off for my entire device	Yes
New Circuit (blocked)	a service has blocked the IP address of my exit node	request a new circuit	find an exit node the service hasn’t blocked	Research
New Circuit (slow)	A service is especially slow over Tor	request a new circuit	I can find a faster circuit to improve the speed of the service I’m using	Research
Connection status	I open the Tor app	see the status of both my Internet and Tor connection	be confident my traffic is being routed through Tor, and debug any connection issues if not	Yes
Connection error	my Tor connection has been interrupted	receive a warning that I’m no longer connected to Tor	understand how to remedy the issue and reconnect	Yes
Moat connection test	I’m not sure what the root cause of a connection issue is	test whether or not I can reach the internet securely	determine if the issue is due to my Internet connection or Tor	Yes
Network speed	I browse the Internet via Tor	do so with a connection speed comparable or better than other VPN providers	maintain a usable speed in spite of a poor connection or throttling	Yes
Data usage chart	I’m connected to and routing my device’s apps over Tor	see a chart of my up/down data over time	feel reassured my traffic is being successfully routed through Tor, and monitor my data usage	Yes
No interruptions	I’m using the Tor app	not see any subscription popups or advertisements	configure the app and connect to Tor without any interruptions	Yes

Onion Services

Feature	When...	I want to...	So I can...	MVP?
Onion sites	I want to visit an onion site	enter the onion site’s address in my web browser of choice	access the onion service privately using my regular web browser	Yes
Human-readable onion addresses	I want to visit an onion site, but do not have the onion address	be able to use a human readable address instead	easily enter it in my browser’s address bar or share it from memory	No
Onion Location	an onion site is available for a clearnet site I’ve visited in my browser	be notified of its existence and linked to the onion address	discover new onion sites and switch over to them where available	TBC
Block Onion Location	I don't want to be redirected from a clearnet site to its onion site	block this site's onion location	avoid being redirected to the onion site without needing to turn "always prioritize onion services" off	Research
Prioritize Onion Services	an onion site is available for a clearnet site I’ve visited in my browser	automatically redirect to that onion site in future	don’t need to intervene and choose between the clearnet and onion site each time	Yes
Onion Auth	an onion service requires authentication	be able to enter my credentials in my browser	connect to the onion service	Yes
Onion service errors	I visit a broken onion site address in my browser	receive a warning detailing what the issue is	understand the issue and/or the risks of proceeding, if applicable	TBC
Onion site bookmarks	I’m curious about onion sites but I’m not sure where to start	see a list of bookmarks to popular onion sites	discover and visit new onion sites	Research

Help & Support

Feature	When...	I want to...	So I can...	MVP?
Support channels	I’ve encountered an issue with the Tor app that I can’t resolve on my own	be able to access links to help documentation and support channels	figure out how to resolve the issue	Yes
Bundled help docs	I need help connecting to Tor	be able to view the help documentation offline	debug the issue without needing to use another circumvention tool or otherwise connect to the Internet in the clear first	Yes
Bug reports	I’ve encountered a bug with the Tor app	file a report directly from the app itself	notify the app’s developers and receive support without needing to reach out over another channel	TBC
User research	a new user survey or other user research activity is available	be notified within the Tor app	participate in the activity and provide my feedback to the app’s developers	Yes
View Tor logs	I’ve encountered an issue or wish to verify a process happened as expected	be able to view the Tor logs	debug the issue, and forward the logs to others who can help if appropriate	Yes

mentioned in issue tpo/ux/design#35 (moved)

mentioned in issue tpo/ux/research#76 (closed)

removed Doing label

added Next label

removed Next label

added Needs Review Q3 labels

removed Q2 label

Thanks @duncan and UX folks for this really great comprehensive overview of job stories, its super useful for planning! A couple questions:

. What does the TBC acronym expand to in the MVP column? . The issue is labeled with Needs Review in The Tor Project / UX / Research -- are you looking for someone specific in your team to do that review, or just looking for general feedback?

As far as my overview of the Job Stories and their relative MVP status:

. Regarding the Privacy & Security section, the feature killswitch - I think that we should target this for MVP. We don't want unexpected traffic leaks when tor is unreachable, especially because tor circuits can be unreliable at times.

. One thing I did not notice, that has been problematic for other VPNs is local network blocking. When all traffic is routed over Tor, that will also include your local area network traffic, which typically results in you being unable to access your local printer, wifi device, or other local computers on your LAN. It is a good default to block local network traffic, but it should be possible, for advanced settings for someone to optionally override RFC1918 addresses, with a clear indication that is happening.

marked this issue as related to #7

mentioned in issue #7

marked this issue as related to #8 (closed)

Regarding "Quickstart", which is defined as essentially a user restarting their device and connecting to Tor automatically. This is a functionality that RiseupVPN called 'always-on vpn', and I think it could be re-used from there without much difficulty. Its marked as 'Research', but from the Android side of things, this could be integrated fairly easily and I'd advocate that it be moved to being MVP.

mentioned in issue #11

removed S101-O1 label

added S101-O1 label

mentioned in issue #24 (closed)

We created an interview process to reach saturation about what features users most want/need in a VPN. We reach saturation when conducting more interviews won’t provide new insights about the features we're investigating. At this moment, with 8 complete interviews done, there are some features which we can indicate about their state on MVP or not, and some that need more research.

I'm updating @duncan 's table, with the features tagged as "research", and informing their state on MVP based on the interviews.

View the second iteration

Privacy & Security

Feature	When...	I want to...	So I can...	MVP?
Killswitch	my connection to Tor drops out	immediately block all traffic from my device, with the option to override if desired	avoid compromosing my privacy by allowing apps to fallback to a regular Internet connection	Yes [1]
Route all traffic over Tor	apps on my device send traffic over the Internet	easily require all traffic from my device to go over Tor	ensure my privacy isn’t compromised by traffic being sent in the clear	Yes
Quickstart	I restart my device	connect to Tor automatically	browse safely in the event that I forget to connect, or traffic is sent from my device before I can do so manually	Yes
New Identity	I am browsing a website that may not respect my privacy	clear my browsing history, cache and reload my tor circuits	prevent my subsequent browsing activity from being linkable to what I was doing before	Yes [2]
VPN blocking	an app I’m using is attempting to route my connection through another VPN	be given the option to block this connection	prevent that vpn from logging my activity	Research
Proxy bypass prevention	an app is set to be routed through Tor	prevent any traffic leaking in the clear	preserve my privacy and anonymity	Yes
Security settings	I’m reviewing the settings I have applied within the Tor app	see predetermined options for security and privacy	select the settings that best fit my threat model without needing to understand each option individually	No
Unsafe app warnings	I’m routing an app through Tor that may compromise my privacy or security	be made aware about the risks of using the app	make an informed decision about whether to proceed, and moderate my behavior accordingly	No
Turn off network before bootstrapping	I launch the Tor app but haven’t connected yet	prevent Tor from making any connections	ensure my configuration is correct before I attempt to connect	Yes
Application isolation	I’m routing multiple apps through Tor at the same time	ensure that each app uses different circuit	prevent my activity from one app being linked to another	Yes
Prevent DNS leaks	a service on my device performs a DNS lookup	route all of my DNS requests through Tor	prevent my IP address getting leaked to my local network	Yes
App containers	I’m performing more than one distinct activity within an app that supports multiple profiles	containerize these activities	prevent the service linking the activity between each profile	Research

• [1] Along with the killswitch, users also want to be warned about the connection dropping.

Censorship Circumvention

Feature	When...	I want to...	So I can...	MVP?
Connection Assist	I can’t connect to Tor due to censorship	detect and circumvent censorship automatically	connect to Tor and overcome further censorship without needing to configure my connection manually	Yes
Manual configuration	I can’t connect to Tor due to censorship and don’t want to provide my location	be able to manually configure my connection	connect to Tor using custom connection settings, and without providing my location	Yes
Built-in bridges	I can’t connect to Tor due to censorship and I’ve chosen to manually configure my connection	be able to select from a list of bridges	connect to Tor and circumvent censorship	Yes
Request a Bridge	I can’t connect to Tor due to censorship and built-in bridges don’t work	be able to request a bridge	connect to Tor and circumvent censorship without needing to rely on built-in bridges	Yes
Get bridges	I can’t connect to Tor due to censorship and neither built-in nor requesting a bridge works	be able to find alternative bridge lines that are more likely to succeed	provide a bridge manually	Yes
Add a bridge line	I’ve been provided with a bridge line in text format	be able to enter the text string in the Tor app manually	connect to Tor and circumvent censorship using the bridge line I’ve been provided with	Yes
Scan a bridge’s QR code	I’ve been provided with a QR code for a bridge	be able to scan the QR code within the Tor app	connect to Tor and circumvent censorship using the bridge line I’ve been provided with	Yes
Sharing bridge lines	Tor is blocked in my location, but I’ve managed to connect via a working bridge	be able to share that bridge with my peers	help them circumvent censorship and connect to Tor	Yes
Per-app permissions (blocked)	only certain apps are blocked in my location	be able to choose which apps I do and don’t route over Tor	unblock certain apps without slowing my connection or running into issues with others	Yes
No cost	the Internet is blocked in my location	find a circumvention tool that doesn’t charge or feature data caps	access the free and open internet without incurring further costs	Yes

Good usability

Feature	When...	I want to...	So I can...	MVP?
Circuit Display	I’m connected to Tor	see the circuit each app is being routed through	view each relay’s IP address and location	Yes
Exit node selection	services automatically localize their content based on my IP	select the country my exit node is located in	appear as though I’m based in that country	Yes
Bootstrapping	the Tor app is in the process of connecting to Tor	see its progress as it connects	know that it’s working and hasn’t stalled	Yes
Automatic updates	an update is available for the Tor app	be notified immediately within the app	ensure I’m using the most secure and up to date version	TBC
Release notes	I’ve installed a new update	read a changelog within the Tor app	get up to date with bug fixes and changes	Yes
Per-app permissions (slow)	an app or service blocks or is too slow over Tor	exempt that app’s traffic from being routed through Tor	use that app without needing to turn Tor routing off for my entire device	Yes
New Circuit (blocked)	a service has blocked the IP address of my exit node	request a new circuit	find an exit node the service hasn’t blocked	Yes [2]
New Circuit (slow)	A service is especially slow over Tor	request a new circuit	I can find a faster circuit to improve the speed of the service I’m using	Yes [2]
Connection status	I open the Tor app	see the status of both my Internet and Tor connection	be confident my traffic is being routed through Tor, and debug any connection issues if not	Yes
Connection error	my Tor connection has been interrupted	receive a warning that I’m no longer connected to Tor	understand how to remedy the issue and reconnect	Yes
Moat connection test	I’m not sure what the root cause of a connection issue is	test whether or not I can reach the internet securely	determine if the issue is due to my Internet connection or Tor	Yes
Network speed	I browse the Internet via Tor	do so with a connection speed comparable or better than other VPN providers	maintain a usable speed in spite of a poor connection or throttling	Yes
Data usage chart	I’m connected to and routing my device’s apps over Tor	see a chart of my up/down data over time	feel reassured my traffic is being successfully routed through Tor, and monitor my data usage	Yes
No interruptions	I’m using the Tor app	not see any subscription popups or advertisements	configure the app and connect to Tor without any interruptions	Yes

• [2] Most users in this study do not differentiate New Circuit from New Identity, and use it when the connection is slow, similarly to "restart" button on their VPN

Onion Services

Feature	When...	I want to...	So I can...	MVP?
Onion sites	I want to visit an onion site	enter the onion site’s address in my web browser of choice	access the onion service privately using my regular web browser	Yes
Human-readable onion addresses	I want to visit an onion site, but do not have the onion address	be able to use a human readable address instead	easily enter it in my browser’s address bar or share it from memory	Yes
Onion Location	an onion site is available for a clearnet site I’ve visited in my browser	be notified of its existence and linked to the onion address	discover new onion sites and switch over to them where available	Yes
Block Onion Location	I don't want to be redirected from a clearnet site to its onion site	block this site's onion location	avoid being redirected to the onion site without needing to turn "always prioritize onion services" off	No
Prioritize Onion Services	an onion site is available for a clearnet site I’ve visited in my browser	automatically redirect to that onion site in future	don’t need to intervene and choose between the clearnet and onion site each time	Yes
Onion Auth	an onion service requires authentication	be able to enter my credentials in my browser	connect to the onion service	Yes
Onion service errors	I visit a broken onion site address in my browser	receive a warning detailing what the issue is	understand the issue and/or the risks of proceeding, if applicable	TBC
Onion site bookmarks	I’m curious about onion sites but I’m not sure where to start	see a list of bookmarks to popular onion sites	discover and visit new onion sites	Yes

Help & Support

Feature	When...	I want to...	So I can...	MVP?
Support channels	I’ve encountered an issue with the Tor app that I can’t resolve on my own	be able to access links to help documentation and support channels	figure out how to resolve the issue	Yes
Bundled help docs	I need help connecting to Tor	be able to view the help documentation offline	debug the issue without needing to use another circumvention tool or otherwise connect to the Internet in the clear first	Yes
Bug reports	I’ve encountered a bug with the Tor app	file a report directly from the app itself	notify the app’s developers and receive support without needing to reach out over another channel	TBC
User research	a new user survey or other user research activity is available	be notified within the Tor app	participate in the activity and provide my feedback to the app’s developers	Yes
View Tor logs	I’ve encountered an issue or wish to verify a process happened as expected	be able to view the Tor logs	debug the issue, and forward the logs to others who can help if appropriate	Yes

Thanks for this @nah ! How should we read your table, in relation to duncan's? I see it removes various features that were in duncan's table, so I'm wondering how to reconcile that.

I copied the table and moved down only the ones tagged as "research" at Duncan's, and removed the ones that were already "yes" or "no", so it wouldn't be too long to be read again, but now I see how this can be confusing.

I can merge it all -- so we will have the first-version and the constantly updated version. Does it sounds ok?

Makes sense! Yeah, maybe it would be better to merge so we have a 'constantly updated version', I like that idea!

Updated!

I added links to all the issues that exist for all the MVP stories, so we can carry those forwards in any further table updates.

There aren't issues (yet) for the non-MVP items, but when they exist, I'll add those.

The list has been updated.

mentioned in issue #23 (closed)

added VPN MVP label

mentioned in issue #46 (closed)

removed Q3 label

added Q4 label

mentioned in issue tpo/ux/research#70 (closed)

added Next label and removed Needs Review label

removed Q4 label

added Q1 label

Hey @micah, I wanted to produce a final final list for both the pre-alpha and MVP so we can close this ticket – but maintaining markdown labels in gitlab is a pain. Do you have a spreadsheet with the job stories in it I can update instead? If not, I'll create a new one.

There is a spreadsheet where @gaba imported the stories and we used that to come up with the pre-alpha rankings, would that work?

removed Q1 label

added Q2 label

removed Next label

added Backlog label

@donuts this is the ticket you are working on based on the meeting we had in Costa Rica, right?

yes :)