Consolidate documentation

[almet]

Currently, the documentation lives within markdown files on different parts of the repository.

This has the advantage of being simple, but makes it harder to search, and sometimes I have trouble finding the information I'm looking for.

We could have a sphinx tool in place which would compile all this documentation and make it available somewhere, maybe making it available at https://docs.dangerzone.rocks

I see the following advantages:

• The doc will be easier to search
• As part of this effort, we could create an index of our documentation
• We could add some documentation, for instance to help newcomers contribute to the project.

(partial) todolist:

• [ ] Add a contributing documentation
• [ ] Get the list of supported versions out of README.md

[almet]

We've been discussing this today, and we would need to decide what's the best way forward between these two options (I'm trying to summarize and comment on the proposal that have been made during our meeting).

So, two potential ways to handle the docs:

1. Have User facing docs and Contributors facing docs in one place, in a sphinx documentation, or;
2. Have User facing docs on the dangerzone.rocks website and the contributing docs in a sphinx documentation.

1. Have all the docs in one central place

Pros:

• It's possible to do the documentation changes alongside the code changes
• It's possible to version the docs, so that it's possible to point to old version documentation if needed (in case we need to maintain multiple versions of dangerzone, which might or might not happen, e.g. when/if we have the Dangerzone packages done by upstream Debian)
• All

Cons:

• It might confuse the users to have a different interface than the website

2. Have the user and contributor docs in two different places

Pros:

• Users can see the user documentation directly inside the website, which becomes their only entrypoint to the project

Cons:

• We will only have one version of the docs (unless there is an option to do that on eleventy, which might be possible)
• Documentation changes will need to be tracked in separate PRs than code changes

There are probably other pros and cons, don't hesitate to update this comment with them. Also, I'm wondering if there is a potential third way where for instance we have sphinx use a theme that is close to what we have for the website, and where the developer facing changes are a bit hidden, for instance.

Also, I would like to mention two things that I think would be worth discussing:

• @eloquence mentioned that the SD docs are writting with .rst (restructured text) and our docs are currently done with Markdown. I'm comfortable with either, and Sphinx supports both. Would it be okay if we stay with Markdown, for instance, or should we move to restructuredText? (it's possible to do the conversion with Pandoc, but in my experience it needs manual intervention on the produced text)

• One goal is to enhance the current situation, where our docs are in plan markdown files rendered by Github, exposing the end users to the Github interface, which is hard to navigate between the different content and exposes them to un-needed complexity. Moving to sphinx and having all the docs in one place (1), even if we decide it's not the end-goal, would in my opinion be better than the current situation, and potentially prepare the ground for further improvements (for instance 2).

I'm curious about your thoughts on this one :-)

[eloquence]

Thanks much for the write-up (and PR!). Some loose thoughts:

• There could be a case for dangerzone.rocks/docs as the home. We already have a build/deploy setup for the site, which we could potentially enhance by adding a Sphinx build step. This could make sense especially if we're going to theme it to look like the website, and re-use some main site components such as the menu.
• I'm not a huge fan of rST; its markup for simple things such as external links and internal cross-references is highly idiosyncratic, and if I haven't used it in a while, I have to look back at examples every time to get it right. SD moved from markdown to rST docs before my time with the project; I think MD may not have supported the full range of organization & layout tools the authors wanted to express. But if Sphinx/MD gives us what we need, I think this could be a nice use for it, and might even motivate us to consider a switch for other docs sites.
• I'm a bit skeptical about docs versioning. The more we make use of explicit versions, the more we risk links pointing to the wrong version making their way into various places - from search engine results to people passing along references to each other, to the links we ourselves create. It's very easy to be toggled to the wrong version and link to it by accident. This is (as far as I recall) why SecureDrop moved away from explicit version builds, to just a "stable" and "latest" version. Even that seems overkill for Dangerzone.
  • Relying on version toggles also risks placing a fair bit of burden on the user ("Oh, I'm using that version, I did not set the toggle correctly").
  • If there are cases where we have to distinguish versions, I'd be more inclined to do so explicitly in the relevant docs, rather than relying on high-level versioning toggle by the documentation tool. This places the burden on us to call appropriate attention to version differences, which is IMO where it belongs.
  • tl;dr: I feel docs-level versioning makes the most sense for stuff like APIs or libraries, but less for an end user desktop tool.

[almet]

We've had a nice conversation today about documentation, and found that the following sections would make sense in our documentation.

The Dangerzone Guide part would be done on the dangerzone.rocks website, where the rest of the technical documentation would happen with sphinx, potentially on a dev.dangerzone.rocks website.

We found that the "Contribute" page of Securedrop is really good at being an entrypoint, and probably want to replicate / copy some of them to our own docs.

Here's the structure:

• Layperson Docs “Dangerzone Guide”
  • What is Dangerzone?
    • How does Dangerzone work? (for laypeople)
    • Dangerzone for Journalists
    • Similar Projects
  • Usage
    • Installation
    • Using the Desktop App
    • Advanced Usage
      • Using the CLI
      • Using on an airgapped device
      • (possibly these are both brief sections that link to technical docs)
  • Security? (duplicated from technical docs?)
  • Reporting Issues
• Technical Docs
  • What is Dangerzone?
    • How does Dangerzone work? (for techies)
  • Security
    • Advisories
    • Audit
    • Reporting Issues
  • Technical documentation
    • Running locally
      • APIs
        • Container APIs
        • CLI API in detail
    • Technical Architecture
      • Gvisor/Containers/GUI
      • Link to blog post
      • Reproducibility
      • Updater
      • Qubes integration
  • Contributing
    • Contributor guidelines
    • Links to contributor resources
      • GitHub, easy first issues, etc.
    • Running tests
    • Sending a PR
  • Release Process
    • QA
  • Changelog
  • License

[almet]

In addition to what's already been discussed, we have been thinking about having the application point to online documentation, especially in errors for which we know that an answer exist.

This will allow us to make answer evolve as time goes, and hopefully enhance the user experience when they're blocked.