Standardize and polish for docs restructuring

[ChumOfChance]

Fixes #790

The goal of this PR is to apply some style and formatting standardization, as well as polish, to the current main branch. Our docs already had inconsistent application of styles and terms and this has been exacerbated by combining two previously distinct documentations. This branch is slated to be published as a major restructuring of the docs when we hit a version of SecureDrop that is fully Qubes-based.

• Standardize use of terms
  • "email" over "e-mail" following AP style and similar small changes
  • I've applied the preferred term "USB flash drive" as opposed to the myriad of different options that were being used, based on Wikipedia's preferred term: https://en.wikipedia.org/wiki/USB_flash_drive
  • "Onion Service" as per our glossary, "onion address" as per the Tor documentation, "onion name" or "short onion name".
• Remove use of Title Case in headers and subheaders in accordance with FPF's preferred style
• Update Glossary and consistently apply italics to Glossary Terms terms of art in the text
  • A few terms like "Admin Interface" were previous title case and italicized like other glossary terms, despite not appearing in the glossary. I've applied that formatting consistently to all such "terms of art" that were previously italicized + title case, regardless of whether they currently or ever did appear in the glossary.
  • There are few exceptions, for example "journalist accounts" (accounts of the journalist type) and introductory text referring to journalists and sources in more general terms
  • Restored or partially restored a few terms to the glossary I had previously removed
  • I've tried to steer this PR away from what should be in the glossary/formatted as a "term of art". I think there are few discussions needed there and probably another PR down the line. In this case, I am just trying to apply consistent formatting and style.
• Replace remaining references to "App" with "Inbox"
  • Also cleaned up other references to "Application" which could be confusing
• Fix whitespace
  • Made the use of extra lines around headers consistent, which improves readability of the source
• Fix frequent use of U+2019 (right quotation mark) in place of apostrophe

I intentionally skipped over the training schedule, as it is currently on the way to removal #809

[nathandyer]

These changes are looking great! I know this was a massive undertaking, thank you so much @ChumOfChance

A handful of things I noticed as part of this first review pass:

• SecureDrop Inbox should be added as an official glossary term, and treated as such throughout.
• Journalist is not consistently italicized as a glossary term. Sometimes it is, sometimes it isn't.
• I thought I recalled us deciding that Administrator would be part of the glossary to match the other user roles. (I may be mistaken). Either way, I think it should be, and treated the same as Journalist or Source when necessary.
• Sometimes the random capitalization in the middle of a sentence when a glossary term pops up feels a little jarring. I'm wondering if the italicization is sufficient, and requiring them to be capitalized every time is overkill?
• We should add the glossary terms from the TODOs as part of this PR
• I see we're looking to standardize on the term "USB Flash Drive". I'm curious if that's the most user-friendly term. At first glance, "drive" probably doesn't mean much to most people (I vaguagely recall we had this discussion in years past and settled on "device"). Flash is likewise only meaningful to some. I tried to find a previous conversation we had about this, but was unable to do so. I know at once point in time we had terms like "thumb drive" mixed in, and I think in general we started just using "USB drive," although that's less descriptive because it doesn't clarify between a flash drive vs a portable hard drive/SSD, etc., and it is also problematic because it uses the word "drive" like I mentioned above. Maybe there isn't a perfect term? In any case, I'm fine with using "USB Flash Drive," I just want to make sure we're intentional about it.
• Do we feel that using "onion addresses" across the board, and not specifying the . part to emphasize that addresses end in .onion, will be clear enough to end users? (Probably so, just asking)

[nathandyer]

Suggested change

	Because the air-gapped Secure Viewing Station has no Internet access, updates can only be performed using
	Because the air-gapped *Secure Viewing Station* has no Internet access, updates can only be performed using

[nathandyer]

This is one instance, but this whole section needs to be updated since that's a glossary term

[ChumOfChance]

Secure viewing station is actually not in the glossary anymore. The SVS will be a legacy item only relevant to people migrating, so I don't think it should appear in the glossary? Instead the title case here should be removed.

I also changed many cases of "SVS" to "secure viewing station" since I think we should be avoiding acronyms like that in the documentation (especially when we will be referencing something from the previous gen of SecureDrop. Looks like I missed a few though!

[ChumOfChance]

I forgot to mention an important thing which is that I intentionally tried to not make change to the threat model page beyond the title case changes. The threat model feels like an external document for reference, it's authored outside of the rest of the docs (and I think expects a big revision soon to bring it up to date with a fully Qubes-based SecureDrop). Being published inside the docs I felt removing title case from the headers was needed in this PR, but I didn't want to go through and fuss with all the glossary terms (there are also a lot).

But I can see how that will make this PR cleaner, even if it might be changed a bit later!

[ChumOfChance]

Re: the glossary, I planned to do a subsequent PR that specifically addresses the glossary fixing #814 and #813 ; few of the definitions need to be updated, some added, and then apply the italicization to the new glossary terms.

I wanted to keep that work out of this PR, and focus this more tightly on style/standard terms/formatting (it's already so massive). I only added back two glossary terms that were already mostly italicized in the text, and adding them back should be uncontroversial (Admin and Journalist Workstation are terms we are reusing with new definitions, and they were removed from the glossary in a previous PR by me I think, prematurely). This PR should be consistent (everything in the glossary is italicized).

[ChumOfChance]

Re: ".onion", I think ".onion address" is not a good term to use. Onion services are reached using an onion address, which is a long string of characters ending in ".onion". I think it's better to describe that relationship coherently when needed (like in the glossary), and I think users will understand. I think we should definitely not use ".onion address" every time it appears in the documentation, and previously we had a mishmash of many different terms.

When it is necessary, we should point out explicitly that an onion address ends in ".onion", or that it's important to include the ".onion" when copying and pasting an onion address. There are a few examples in the docs, e.g. in the source documentation I left in:

Using Tor Browser, find the ".onion" address for the SecureDrop for
the organization that you wish to submit to.

Which I think is a good way to succinctly communicate to the a source user in a very non-technical way (but I think the quotes are important here!).

I did notice an errant .onion which I think should be changed to regular quotes while searching for the above example though!

[ChumOfChance]

I agree with you about the capitalization + italicization. I think dropping the title case from glossary terms when they appear would be a good chance, if you think we can make that call I'm game to add it to this PR.

[ChumOfChance]

Saving the most controversial for last 😆 re: "USB flash drive". We had so many different terms for this and I am sure it has caused confusion for users. I went to Wikipedia to settle the issue, which prefers "USB flash drive" ("also known as a thumb drive"). If there is a better precedent or resolved discussion for SecureDrop's preference I can abide that rather than opening the can of worms, but of the available options I'm inclined to agree with Wikipedia.

It is a mouthful, but it's descriptive. If we think it's too wordy, I think a compromise would be to invoke "USB flash drive" when being explicit, the first time it is mentioned in a page/section, and then more often shortening to "drive" thereafter in the same page/section. This will give us things like Admin Workstation drive, Tails drive, Qubes installation drive appearing after "USB flash drive" has already made it explicit that this is referring to one of those little USB stick keychain thumb-sized things.

[ChumOfChance]

I did some more work and updated the PR description. @nathandyer I think in particular the glossary/italics stuff should be easier to review, sorry it was still a loose before. Other open questions remain but I think I've replied to all your review comments so far.

[nathandyer]

Thanks @ChumOfChance, I'll do another pass and also reply individually to your inline comments/messages as time allows. Hoping to take another look today, but if not, I'll get to it early next week.

[nathandyer]

Thanks @ChumOfChance, these changes are looking great!

I definitely like saying Secure Viewing Station in place of SVS consistently, and treating it like a glossary term (although as you note the SVS is effectively on its way out with the transition to Qubes, so its days are numbered beyond a forthcoming Tails -> Qubes migration guide).

I noticed you changing "Daily Journalist Alert" to "daily journalist alert", presumably because it's not part of the glossary. I do think it's worth thinking about if it should be, and potentially making it stick out more just so it's clear to users that it's its own special thing ™️

In any case, I feel like this is getting close to landing. Once you're back, let's find a time to chat through some of this (maybe synchronously?) and we can get this merged so we can build on top of it. With such a big change, I don't want to start making too many changes without this landing first.