securedrop-docs
securedrop-docs copied to clipboard
freedomofpress
Create section at top (before User Guides) for intro material & frequently referenced things
Description
Within "Deployment Best Practices," the sub-section 'Minimum Requirements For SecureDrop' feels very out of place. Likewise, I can never find the dang "Glossary" when I need it... and the "Overview" in "Installation Guide" feels like a better general SD primer than specific to an installation task.
A lot of important reference information appears to be buried at the start of the "Installation" section, with "Before You Begin" being the 5th sub-section therein; which is also mighty awkward.
Without the "Minimum Requirements" sub-section, the rest of the content within "Deployment Best Practices" much more elegantly speaks to processes relevant to learn about and reference after completing an installation. As self-identification and co-branding guidelines are published for the Source UI and landing pages, they will most elegantly live with the rest of the content currently nested in this section.
Recommended Solution
- Create new primary section (blue text) called "About SecureDrop"
- Locate this new section above "User Guides"
- Move the first 3 sub-sections of "Install SecureDrop" into "About," along with "Overview" and "Minimum Requirements" from "Deployment Best Practices"
- All these pages provide very high-level overviews, which are relevant when a person is considering SecureDrop—before making that commitment. Likewise, they're relevant to all users in a variety of scenarios, and are far easier to find in their own general section, than buried in two sections that only target IT workers.
- Move "Passphrases" to just after after "Before You Begin," in Installation; the latter should be that section's first section. It's... odd, to show "Before You Begin" as the 5th sub-section.
Resulting IA should be...
- About SecureDrop
- Overview
- Existing sub-section, currently named "Overview" within "Install SecureDrop"
- Glossary
- Why is this most fundamental bit of reference material, buried w/in the Installation guide?
- General Requirements
- Existing sub-section, currently named "Minimum Requirements For The SecureDrop Environment" w/in "Deployment Best Practices"
- This page needs some love to separate-out hardware things from _connectivity thing_s from physical space things from ongoing lifecycle needs.
- Page's title also needs to be simplified; "environment" as it's currently used is very specific to Dev/IT jargon that will not resonate with others who may also be looking for that information
- Hardware: Required, Optional, and Recommended
- Existing sub-section & child sections, currently just called "Hardware" w/in "Installation Guide"
- Because this feels like VERY DENSE reference material I cannot see as only relevant when actively installing an instance... and I could see many folks being lost looking for this, before and after committing to host an instance.
- Overview
User Stories
- Having installed my SecureDrop instance, I need a clean/clear section that instructs me all about what to do next.
- As a person coming to RTD with any of a variety of needs and motivations, I would like easier access to core reference information, outside specific task-themed topic buckets.
- WTF, this Issue's title was totally misleading—there's way more you're asking for here, Nina!
WTF, this Issue's title was totally misleading—there's way more you're asking for here, Nina!
You took the words right out of my brain :)
I agree with the simple move of the "Minimum Requirements" section; the rest requires a bit more discussion & review than we have bandwidth for right now. Would recommend scoping more tightly; if you want to keep scope as is, we can re-title but will likely not be able to get to it soon.
So... I'd love to scope-down this issue, but I honestly don't know of anywhere else that awesome "Minimum Requirements" section could get moved to. "Glossary" being buried w/in "Installation" and zero general-overview of SD being surfaced at the top, have always also stood-out to me as big gaps.
"Topic Guides" feels like a great catchall ditch-zone for just MinReqs, but as much as that is far more realistic to do as a one-off, it pushes the broader IA issues of the docs a step backwards imho.
Maybe I'll change my mind closer to the 1.0 release, but I just feel very... ugh, dirty, recommending "easy to implement!" things that create more debt to the bigger-picture, while, sure, alleviating one little thing for my one need.
"Basics" came to mind last night, as a nice name for such a section. "Glossary," "Is SecureDrop Right For Me?" and "How It Works" (as a brief summation of what's in "Overview" w/in "Installing SD" could very elegantly live within it, and imho could help a lotta folks.