Update v2/v3 Onion Page Text

[ninavizz]

Describe the change

Hi Gang! Until I learn Git a little more, I can’t really do PRs on my own, but wanted to flag the request for some edits to this page in the Docs. Edit suggestion, in comment below. These edits are important for the user experience and comprehension of info to be smooth, when folx click on the link in the new JI banners telling them to upgrade.

How will this impact users?

The page is confusing and a challenging read at the moment, for users arriving on the page from the banner we'll be pushing live in 1.7.0. It's important to communicate with users what we need them to know, first; and everything, later.

The "Order Of Consequence" with the text on this page, seems to be:

1. v2 is going to be depreciated, and you have until April 30th to not be screwed by this—know that.
2. You need to update your onion address on your Landing Page if you've already done the migration but haven't done that part.
3. If you don't do the above, your Sources will not know where to go.
4. Here is why all of this is happening.
5. Here is how to do it all, if you haven't already.

The topical 101 in the first paragraph of a page, is also quite confusing. Per #123 I'm recommending creating a new item in the glossary, and moving the existing content there.

With the increased urgency of getting users to Update, it feels extra important to prioritize user engagement for this page when users link to it from the 1.7.0 JUI banner.

User Research Evidence

Nope! Someday, though. :)
Recommendations from UX SME follow general best-practices for writing instructional content that users need to follow.

[ninavizz]

Suggested edit notes

1. Re-order content on page to present in a "needs to know" order, to respect user attention spans and promote correct urgency, when read from banner on 1.7.0

• Remove pleasant-yet-verbose language such as "Because of these important improvements..."
• Text should not read conversationally nor educationally, but bulleted-ly. If that makes sense. "Need to know," not helping ppl learn. Don't remove the user's agency to simply do things quickly; they need to want to make the time investment to learn, for learning info to be useful vs distracting or interfering with simply getting something done.
• Move styling of "Important" module to the top of page, as implied by Markup styling in comment below.

2. I know the content of this page speaks to The Landing Page, but it's important to call that out to users by spelling it out; and showing that early. Also helpful, to include link to the Glossary item. This is one of the highest priority items for users to grok and act upon, so it needs to be spelled-out. Below draft uses an empty hash to style text as a link.
3. Move "Onion Services 101" content to glossary item, and remove from page. Below draft uses an empty hash to style text as a link.
4. Remove confusing use of word "currently" to disambiguate v2 from v3 services. New/Old mental models should be used with this, not "Current/Former," as they're both still live and therefore technically current atm.
5. Updates text above examples of v2 and v3 service address examples. Existing text is structured to require users "to think" instead of following more common UI patterns for qualifying information.
6. Including words like "Cryptography Primitives" is discouraged, as so few users will understand what that means for the specificity to have value. I moved that bit to suggested text for the Onion Services glossary item.

[ninavizz]

@eloquence In our chat yesterday, you mentioned that users also need to turn-off/discontinue their v2 onion pages, for their migration to be considered "successful"? We don't mention that, on this page. It should be mentioned on this page, imho. Likewise, some link to instructions for how to do this—assuming such content exists somewhere?

[ninavizz]

This link blab also needs to be edited to present v2 vs v3 as less optional. Recommend against using "Next Generation" as a user-facing phrase in documentation. v3 vs v2 sounds adequate w/o additional qualifiers, as the text is for admins.

[eloquence]

In our chat yesterday, you mentioned that users also need to turn-off/discontinue their v2 onion pages, for their migration to be considered "successful"?

That's advisable; the migration to v3 is also enforced as part of the migration to Ubuntu 20.04 (after April 30, it will not be possible to run a live instance on v2 onion services). We do have documentation for this, in this section:

https://docs.securedrop.org/en/stable/v3_services.html#disabling-v2-onion-services

I agree we should simplify and reorganize the v3 chapter of the docs a bit. We should also make clearer how the v3 migration relates to the Ubuntu 20.04 transition.

This link blab

I'm not sure what you're referring to here. I don't see the phrase "next generation" anywhere in the linked page.

[ninavizz]

That's advisable; the migration to v3 is also enforced as part of the migration to Ubuntu 20.04 (after April 30, it will not be possible to run a live instance on v2 onion services). We do have documentation for this, in this section:

So... that sounds to me, like they'll have to do it? I totally respect the soft-language approach for open source. I just question if we're making our own or our customer's lives harder, by not being simpler, clearer, and more direct with them. Between the Docs page I'm referencing with this issue, and the mention of Ubuntu in April, I'm left to ask "Which is it—February or April?!" as I'm reading one thing in one place, and hearing another thing in another place.

I'm not sure what you're referring to here. I don't see the phrase "next generation" anywhere in the linked page.

Doh! Installation > Onion Service Options linkfail, sorry!

[ninavizz]

Updated suggestion for page's text, below. Looking forward to getting more comfy with GitHub in the near future... ty again Erik for the instruction so far!

---

SecureDrop v3 Onion Services

Important: Beginning April 2021 v2 onion addresses will become unreachable. If your SecureDrop's Landing Page currently shows a v2 onion address (16-characters), you need to update it to the newer 56-character v3 onion address. URL forwarding is not done with onion addresses, so you must update the address on your Landing Page for Sources to continue finding your SecureDrop.

SecureDrop supports the newer v3 onion protocol, and is phasing-out support for the v2 protocol. Beginning in February 2021, new SecureDrop installs will only support v3 onion addresses.

The newer v3 onion services protocol provides stronger cryptographic protections than v2 onion services, including improved mitigation against service information leaks on the Tor network. Because of these important improvements, the Tor project is deprecating their own support for v2 onion services. With SecureDrop's 2.0 release on April 30, 2021, pages on v2 onion services will no longer be reachable.

v3 onion addresses are 56 characters long - shown below in an example:

http://vww6ybal4bd7szmgncyruucpgfkqahzddi37ktceo3ah7ngmcopnpyyd.onion/

v2 onion addresses are 16 characters long - shown below in an example:

http://secrdrop5wyphb5x.onion/

We recommend that you follow the v2+v3 migration path below, and test v3 functionality thoroughly before :ref:disabling v2 onion services <disable_v2>.

Migrating from v2 to v3 only or v2+v3

Preparing for the migration

Before starting...

[eloquence]

Doh! Installation > Onion Service Options linkfail, sorry!

Great catch, we should definitely update that paragraph.

So... that sounds to me, like they'll have to do it?

Yes. We recommend that they do it ASAP, before the Ubuntu 20.04 migration (which isn't even supported yet with this coming 1.7.0 release), so they don't have to handle two complex upgrades at the same time. But they can also do the two together -- the ultimate deadline is April 30. I agree the docs should re-center the April 30 deadline at this point to keep it simple.

[ninavizz]

Yes. We recommend that they do it ASAP, before the Ubuntu 20.04 migration (which isn't even supported yet with this coming 1.7.0 release), so they don't have to handle two complex upgrades at the same time. But they can also do the two together -- the ultimate deadline is April 30. I agree the docs should re-center the April 30 deadline at this point to keep it simple.

Ok, then the text I composed above seems to be inaccurate. When will v2 onion services literally stop working? The "Update your Onion on your LP!" CTA sounds most urgent, and I want to ensure we don't mislead users while also not confusing them.

Also: Your brain must need a proper 2 week nap more than just over the holidays, this is SO MUCH to keep straight! ;)

[ninavizz]

(Also, I updated the first 2 comments on this Issue—sorry it's been all a bit jumbled and confusing. Looking forward to being able to do PRs on my own!)

[zenmonkeykstop]

One thing to bear in mind is that users may also be coming to that page directly while browsing the documentation, so preamble (what is this? why should I care?) is important in that scenario. You could have the least-worst of both worlds by linking to an anchor in the doc from the banners, ie: https://docs.securedrop.org/en/stable/v3_services.html#migrating-from-v2-to-v3-only-or-v2-v3

In fact, given that we'll have separate banners for each case, we could probably link to docs specifically covering the appropriate workflow for each case.

[rocodes]

I like @ninavizz's suggested changes to the docs. I do agree that the docs are both explaining/contextualizing ("what are onion services and why should I care?") and also instructional, which makes for a mixed tone and loses some of the urgency of the instructions.

I would be happy to work on docs changes to accompany @zenmonkeykstop's JI changes. I'd also be happy to work with you on making your own PRs, nina.

[eloquence]

We'll consider these improvements as part of the 1/6-1/20 sprint. Because we will direct admins to this page from the Journalist Interface, we should IMO make sure that we also mention the coming Ubuntu 20.04 transition on it, as it's the other major coming operation that needs to be on admins' radar.

One point of clarification @ninavizz: Per the updated roadmap, SecureDrop 2.0.0 will be released after April 30, and we can IMO remove explicit reference to that version here. 2.0.0 will be the first release that drops support for Ubuntu 16.04 (a compatibility-breaking change that justifies the major version number increase), but the April 30 deadline will be enforced on older installations by disabling the Source Interface after April 30 (freedomofpress/securedrop#5688).

[ninavizz]

Are you guys trying to make my head go-splodey with all the dates/releasedetails/etc? ;)

Per @zenmonkeykstop's comment about who is reading the docs and how—I do actually appreciate that a lot, and have thought that perhaps a blog post speaking directly to the general public and folks landing onto a page from an in-site banner, could be more appropriate?

Tomorrow (Thurs) I'll also be OOO, but will poke at drafts for both a blog article, and subsequent Docs update to this page.

Per item number 6 the my comment in the banner ticket, @zenmonkeykstop I still would like to get a (simple/brief) checklist in that location, so admins can quickly look at it to determine if they've missed a step. Likewise, in the blog article I'd like to speak to why a user may see the "Partially done, still got stuff to do!" banner—so some more background for myself, here, on why that gets triggered vs the other banner, would be muio helpful. :)

[gonzalo-bulnes]

Was fixed by #136. (GitHub recognizes Fixes #... but not Fixes Issue #....)

[eloquence]

Thanks @gonzalo-bulnes, closing.