Create "Onion Services" item in Glossary

[ninavizz]

Describe the change

Create a new item in the glossary for Onion Services. Cited as need for #122

Text from existing Onion Services blab in docs, reads as follows—and seems like a perfect starting point. I would also suggest adding-in something about the .onion suffix and unreadable URLs that are 16 (v2) or 56 (v3) characters (that they exist, not details about v2 vs v3 or depreciation). Frame as "New vs Previous" not "Current vs Old," as both remain live today.

Tor onion services provide anonymous inbound connections to websites and other servers exclusively over the Tor network. For example, SecureDrop uses onion services for the Journalist and Source Interface websites, as well as for administrative access to the servers in SSH-over-Tor mode.

Also

The longer v3 addresses provide stronger cryptographic primitives (algorithms) than v2 onion services, and include redesigned protocols that guard against service information leaks on the Tor network.

How will this impact users?

Will make blabs on technical Onion stuff more readable and easy to consume, if the 101 stuff can live in a glossary listing vs in page content. Is also useful for all users to be able to reference from user guides.

User Research Evidence

Nope. That would be so nice, though. :)

UX SME notes the above suggestions follow general best practice for content consumption, and advises y'all to please do. UX best practices informed by research by practitioners. Nope, we don't do RTD or otherwise have shared best practice knowledge documented as copiously well as developers document coding languages and rules.

Generalized resources for best practices wrt content writing, IA, etc., for docs, in UX repo.

Additional context

Just wanting to make Docs more actionable and content easier to consume. :)

[gonzalo-bulnes]

I would be happy to work on docs changes [...]. I'd also be happy to work with you on making your own PRs, nina.

I happen to have the docs setup and be looking at the Glossary (#117).

I'd be happy to open a PR applying the changes that @ninavizz described to that page, but will hold off unless told otherwise because it is also seems like a good opportunity to pair on a PR and @rocodes may have work in progress already.

Please let me know if I there is anything can help with @rocodes @ninavizz 🙂

[gonzalo-bulnes]

Since the Glossary stands alone and some readers may not have additional context, I think it may also be useful to add a short description (or example) of what onion services addresses look like before talking about the differences between v2 and v3 versions?

[...] to the servers in SSH-over-Tor mode.

Onion services can be accessed by clicking a link or pasting the onion service address into Tor Browser. For example, nytimes3xbfgragh.onion (note: could be a link) is the address of the New York Times' v2 onion service.

The longer v3 addresses provide [...]

[gonzalo-bulnes]

Nitpicking, I believe the versions apply to the onion service, not only their address?

The longer v3 addresses provide stronger cryptographic primitives (algorithms) than v2 onion services [...]

Suggestion:

The third generation of onion services (v3) have longer addresses. They provide stronger cryptographic primitives (algorithms) than v2 onion services [...]

[eloquence]

Hi @gonzalo-bulnes, by all means, if you have time, it would be great if you could take a crack at a PR for this issue. Note that we're aiming to beef up the docs related to v2/v3 by the time of the SecureDrop 1.7.0 release (2021-01-26), which will place additional emphasis on encouraging users to make the switch.

Since the Glossary stands alone and some readers may not have additional context, I think it may also be useful to add a short description (or example) of what onion services addresses look like before talking about the differences between v2 and v3 versions?

Yes. Perhaps we can start the glossary entry with an explanation that's based on v3, and then add a paragraph (possibly separated by a sub-heading) to clarify the distinction between v2 and v3, which can be removed at a future time when v2 support is fully removed.

I would recommend using the SecureDrop.org address as an example .onion address (sdolvtfhatvsysc6l34d65ymdwxcujausv7k5jk4cy5ttzhjoi6fzvyd.onion). We want to avoid referencing the .onion addresses of live SecureDrop instances in the docs, to minimize the risk of proliferating an old address in case of a change.

[gonzalo-bulnes]

I'm happy to open a PR, that will help me understand how you're thinking about the Glossary as well. 👍

Perhaps we can start the glossary entry with an explanation that's based on v3, and then add a paragraph (possibly separated by a sub-heading) to clarify the distinction between v2 and v3, which can be removed at a future time when v2 support is fully removed.

👌 I'll draft something to see how it looks. I've been thinking about introducing some sub-headings in the context of #117 and this is a good use case to see how that could work.

I would recommend using the SecureDrop.org address as an example [...]

💯 Makes a lot of sense to me.

[gonzalo-bulnes]

we're aiming to beef up the docs related to v2/v3 by the time of the SecureDrop 1.7.0 release (2021-01-26)

Got that, thank you for the emphasis/reminder @eloquence 🙌