Set up RTD for SecureDrop Workstation

[eloquence]

We may want to consider setting up a separate ReadTheDocs instance for the SecureDrop Workstation, for a few reasons:

• The versioning schema used on https://docs.securedrop.org/ is tied to SecureDrop Core; the workstation is versioned independently.

• We should aim for user-friendly, accessible end user docs that don't get lost in the information architecture of installation and maintenance instructions for the conventional SecureDrop setup.

Using a separate instance may also open up options for more end-user-friendly theming (e.g., making search more central).

[eloquence]

A couple of alternatives that are worth mentioning:

• Using securedrop.org itself - gives us the full flexibility of Wagtail, but docs are no longer part of our regular review processes. I value the cross-team visibility into docs changes we currently have thanks to having it all show up on our GitHub board, and the shared sense of maintainership.

• Using a dedicated knowledge base software - @ninavizz made the argument to me that commercial knowledge base software may be a better fit for easily searchable end user docs (think https://slack.com/help). This does have the same problem as Wagtail in separating doc authorship from development. That said, the usability arguments against RTD for end user docs are pretty compelling. My bias is to see how far we can get with theming it over time, instead of replacing it with something else for one component.

[rocodes]

At least for the pilot, I'm in favour of a separate rtd instance and of keeping it simple with workflows we already use/are accustomed to.

[ninavizz]

No commercial KB exists w/ decent enough privacy protections (cuz, yay, analytics) so I am also in favor of a separate RTD instance. On an aside from also valuing keeping the same workflows everyone is used to.

[conorsch]

The primary downside to a separate repo for docs is that it becomes harder to ask for docs updates during PR review. However, given how many repos we have in play for the Workstation, there's no single repo (not even this one) that's the perfect fit, so separate repo sounds best.

Using RTD rather than a more custom bespoke solution seems like it will serve us well. Anything using Wagtail will likely live in the database, meaning we cannot as easily involve external parties in docs improvements. Perhaps not critical-path to make sure the docs are editable by external-parties, but I'd very much prefer a solution that supports public contribution.

If we do decide to stick with RTD, we'll need to declare a URL, e.g. workstion-docs.securedrop.org, and set that URL in two places:

• https://readthedocs.io admin panel
• web server reverse proxy settings

So just ping infra team when a decision is made.

[eloquence]

I was thinking we could use this repo (which does seem like a reasonable fit IMO) in a docs structure, and publish to a separate RTD instance.

[conorsch]

@eloquence Ah, I must have misunderstood your comments during standup about a "separate repo"; If you mean "a repo other than https://github.com/freedomofpress/securedrop/", I fully agree!

Consider using git-lfs for screenshot storage, since the repo is likely to balloon over time otherwise.

[ninavizz]

A consideration Erik and I have discussed to explore with an RTD instance mirrored at the SD domain, is creating a custom "entry page" experience—to spare non-dev users the shock/awe of technical documentation as an entry experience.

Nothing fancy, just a few simple entry-points and friendly text for different user types (Journalists, Admins, Developers), with a lower-page blab that sets expectations for how to use what can feel like an overwhelming experience for users acclimated to consumer-help models (so, explicit guidance on using the tree structure—which is increasingly uncommon these days).

• "Journalist" user path wd direct users to an instance w/ JUST a journalist user guide.
• "Admin" user path wd direct users to an instance w/ both an Admin and Journalist user guide.
• "Dev" user path wd direct users to an instance with everything.

I do feel that RTD can be a navigable experience, with a well considered IA and a tiny bit of up-front hand-holding.

[eloquence]

Consider using git-lfs for screenshot storage, since the repo is likely to balloon over time otherwise.

Sounds good. From what I'm able to find in GitHub help, that's just a matter of tracking those files using LFS, and this can be done in any existing repo including this one, correct? Or would we need to change the configuration of this repo if we wanted to use LFS here?

[eloquence]

Also, it looks like RTD does not support out of the box builds with LFS as of this comment, so would require some additional config.

[pierwill]

My two cents:

A RTD site living at workstation-docs.securedrop.org and built from docs/ in the securedrop-workstation repo is a good way to go.

@ninavizz and @eloquence's idea of an end user landing page is also a great idea.

I'm happy to contribute to this project in 2020: writing, setting up, maintaining, whatever is needed!

[ninavizz]

@pierwill You are so lovely, thank you for your enthusiasm for and hard work in support of SecureDrop! :)

Erik (eloquence) and Jen (redshiftzero) Conor (conorsch) and Ro (rocodes) are all on holiday for the next two weeks. We'll all be back at it, come January 7th. Have a great holiday, and I look forward to working together some more, in the New Year! :)

[ninavizz]

BTW, a REALLY great article discussing usability in writing documentation... : https://vickychijwani.me/how-to-write-docs-for-people-that-dont-read/ ...with many included videos showing user researchers discussing relevant studies. No whitepaper drivel, just good practical stuff. :)

[eloquence]

In sprint planning today, @conorsch advocated for a securedrop-workstation-docs repo, both for docs review velocity, and for reducing repo checkout size in case we add a lot of media assets.

As the URL, I would vote for simply workstation.securedrop.org.

@rmol mentioned https://www.getlektor.com/ as a potential alternative to RTD given good i18n support. I personally would vote for sticking with what we know so we don't have inconsistent workflows between projects (RTD also has i18n support). @rmol, if there are strong arguments in favor of Lektor we should consider before finalizing this decision, please jump in!

A final important question is what should live in this docs instance:

• user docs
• admin docs
• developer docs

I would vote for user & admin docs. For developer docs, it seems like we may be better off sticking to the wiki for higher velocity. Thoughts?

[rmol]

I think Lektor's too much of an unknown quantity given our timeline. It's used for the Tor manual, so it must work well, but a quick look at its i18n story suggests it's not worlds simpler than RTD; we'll have to extract gettext files for Weblate either way. And we'd have to host the docs ourselves, which is not a big deal, but involves new infrastructure decisions and commitments that we don't have to make if we stick with RTD.

Last but not least, the most likely contributors to the docs are already familiar with Sphinx/ReST/RTD from SecureDrop core.

[eloquence]

We do have a build from https://github.com/freedomofpress/securedrop-workstation-docs to https://securedrop-workstation-guide.readthedocs.io/en/latest/ . This URL is unlikely to be stable, so recommend linking against it at this point, but handy if you don't have a local build environment. Docs still WIP. Leaving this issue open until we have finalized a destination URL on securedrop.org

[eloquence]

Said destination exists at https://workstation.securedrop.org/ (still with ads :cry: but we'll get to that soon), so closing.