freedomofpress
Reduce up front install documentation
There is a lot of excellent and exhaustive documentation in the SecureDrop installation guide. As an administrator tasked with installing SecureDrop, when I begin the installation process, if I am being vigilant (note: people tend to not read long blocks of text and instead click about and scan the text to find "Step 1: Do blah blah blah" when installing something, we might not like this but it is what happens), I must first read through five pages of documentation: "Overview", "Terminology", "Passphrases", "Hardware", and "Before you begin" - before I get to the first installation step. Some of the documentation - for example "Overview" and "Terminology" contains some repetitive information and is "SecureDrop 101" information relevant outside of an install.
I think we should keep all this documentation. My suggestion is to refactor it a bit to tighten up the installation-specific documentation and move some of the general information relevant for administrators, people considering SecureDrop for their organization, and people just curious about the platform to a "SecureDrop 101" section.
Proposals:
- [ ] Break Overview, Terminology, Passphrases, Hardware out into "SecureDrop 101" header (name negotiable), appearing below "User Guides" and above "Install SecureDrop"
- [ ] Leave "Before you begin" in the install section (which already links to Overview, Terminology, Passphrases, and Hardware), add any critical information that we think people should know, and add a checklist on what hardware people should procure (relevant ticket: freedomofpress/securedrop#1144)
When I install SecureDrop for real and train some people with the current documentation I'll be able to provide real world experience. I suppose you already have plenty available though ;-) This will be in September.
This is still a valid proposal; we should re-evaluate the information architecture of the install guide. Divio's documentation system offers some useful pointers for how explanatory content can be set apart from step-by-step how-to instructions.
