Make Journalist/Source guide mentions of terminology items link to their section in Terminology

[heartsucker]

Description

I did a walk through with a UX team, and they suggested that instead of just italicizing Important Terms and Named Things, we should make them link back to their term in the Terminology section.

[eloquence]

I'm a little worried about overlinking. Terms often occur many times in documents like https://docs.securedrop.org/en/release-0.12.2/backup_workstations.html ; if each instance is linked, that could make it more difficult to focus on the task at hand. If only the first one is linked, that would conflict with our practice of often linking to sub-sections.

Common UX practices I've seen to help the user with the task at hand focus on highlighting the most important related resources/concepts for any specific section. I've also seen clever on-hover glossary styling, but that's probably out of bounds for what we can do with Read the Docs.

Curious what others think about this suggestion.

[ninavizz]

I believe most of what the SS ladies were referring to (in the audit with @heartsucker) were terms in the Source and Journalist sections of the docs—not Developer, Admin, or Installation sections. However, that said—SD's use of nomenclature is imho a bit confusing, and in the docs has been inconsistent (which I know everyone has been working hard at chipping away to improve).

A more user-friendly ecosystem illustration w/ things more clearly named, made available as a poster or as a thing to view while reading documentation, could help. As would the clever hover interactions you mention, Erik. It seems like that'd be a high-value item for RTD to add as a feature, if it's not already in the product or on their roadmap. The SS ladies may have assumed some interactions are available on that platform, that simply are not.

I trust the recommendations of the SimplySecure folks. I'd love to do a holistic UX scrub of the docs, at some point in the not-yet-snowy-again future. Perhaps once UX stuff slows a bit with the Workstation things, and dev is the primary activity @eloquence? As with the Source UI stuff, prioritization would be critical... but it does seem there's a lot that could be improved short of a developer-involved overhaul.

[ninavizz]

^ Actually, having just posted that, my brain is now swimming with "Welcome Kit" ideas of what could be high value to bundle into a small (flat 9x12 mailer, or the 1"H box that L/W size) package to send an org interested in installing an instance... if such a thingy does not already exist?

It's been a common OOBE practice for years, for hardware companies to package illustrated posters folded cleverly, in with device boxes. It seems like SD is a terrific candidate for such a "Basics" poster for folks to handily reference while getting used to the multi-device setup process. Even once the Workstation is ubiquitous.

I'm sure the training peeps have booklets (the iPhone one?) and other ops-sec schwag—and existing laptop-cam and SD/FPF stickers could be terrific). Printed stuff (posters/stickers) can be made for pretty cheap these days. In case, y'know, I'm not suggesting something get created that already exists. Which I well could be.

[eloquence]

I believe most of what the SS ladies were referring to (in the audit with @heartsucker) were terms in the Source and Journalist sections of the docs

If we're just scoping this to the Source and Journalist Guide docs, then I think it makes sense -- those docs sit above the glossary in the ordering, and those two audiences are most likely to benefit from targeted linking.

[eloquence]

Retitled for clarity. Low priority but nice first issue for any docs contributor.

[zenmonkeykstop]

Taking the gfi label off, as it's unclear if this will make sense in the context of the upcoming content reorg work.