Split "User Guides" from "Installer/Developer Docs" in RTD

[ninavizz]

Less of a Story and more of an Epic... but needs to at least exist as a single ticket to get started.

Problem

• Users today lack basic help and how-to resources to guide their use of SecureDrop
  • Source is journalism jargon, and unlikely to draw-in first-time tipsters seeking guidance in using SecureDrop. This is bad, for help documentation.
  • Source users are smacked with a RTD monolith that first requires they identify themselves through industry and legal nomenclature as "a Source," while also understanding there's a whole other SecureDrop universe for Journalists—none of which applies to them.
  • Journalists and Admins need to weed-through content that may or may not be useful to them to find what they need, which is time consuming and can lead to easily overlooking what they need.
  • Ohey, we need to put the Qubes Workstation stuff somewhere, now, too!
• Current documentation is confusing to non-developers (so, most users).
• Robust documentation necessary for developers to install and maintain instances.
• Scaling of documentation over time has gotten chaotic.
• Internationalization has been especially difficult with current format.

Solution

• Immediately extract all guiding content for Sources into a stand-alone artifact, and tweak language to make more user-friendly. Remove dependence of nervous/frightened whistleblowers being able to identify themselves as "a Source." #jargonfail
  • This author (nina!) is not familiar with the nuts-and-bolts of RTD; if it's truly a CMS and can port content into multiple artifacts, that'd be supremely awesome! If not... wayl, we need to start thinking in that direction.
  • Longer-term, craft something that can degrade nicely over Tor and build contextual-help into the Source UI.
  • Rethink how to potentially structure it all to help true user needs & speak to non-technical users effectively.
• Separate remaining RTD content into separate artifacts for Admins, Journalists, and Developers.
• Create new content for Qubes Workstation, and factor-in accordingly.
  • Plan how documentation for all 3 newsroom user types will be initially presented to folks in the Pilot; and ensure it's not confusing to other users, too. Naming the Workstation's app something more unique and calling the Workstation something more unique (even if it's just "Integrated Workstation) will help.
• Reconcile how the 4 different-but-overlapping user-facing artifacts live within repo(s) on GitHub.
• Optimise user-facing content in each for each's intended audience.
  • Coordinate with Training on reshaping Journalist and Admin user content to compliment their work, and to function as a smooth stepping-stone for users immediately after training.
  • Crowdsource user testing of content for Sources.
• Setup each for streamlined localisation.
• Craft a styleguide to guide folks

[ninavizz]

Initial IA recommendation from an IA/UX practitioner would be a great starting point.

• No coding skills necessary
• Basic recommendation of how to split today's content into 3 different ReadTheDocs sites —or—
• How to wordsmith some of today's content for Sources and Journalists to be more human centered and/or user-friendly.

[ninavizz]

A related thought I'd like to discuss with the team @eloquence @redshiftzero @edenemmanuel, and could be a good interim step towards progress on this: renaming the "Source Guide" in RTD to "Getting Started Guide."

• Source is journalism jargon.
  • Source is not understood in broader society to mean a tipster or a whistleblower.
  • When an individual looks to help documentation to guide their early or first use of a product, the they look for is verbiage they can identify themselves with. "Source" is a meaningless term to farmers, biologists, accountants, government workers, etc., at the very beginning of their path as a Source.
• All users except for installers, need to understand the Source experience, anyway—so framing it as a "Getting Started" schtick would not imho be entirely inaccurate.
• The content in today's RTD "Source Guide" is more commonly referenced in other software products today, as "Getting Started Guides." Such a renaming imho will provide a far more intuitive starting-point for all truly-new users.
  • Journalists receive training. Sources don't. And, the updated content in the Source guide is soooo lovely, we should make it more intuitively discoverable.