An organization whose Qubes use I support has developed a substantial internal FAQ. Now upwards of thirty pages, it runs the gamut from:
helping folks without Qubes (or even Linux!) expertise do ordinary things like install software correctly in Debian and Fedora templates; to
guiding them through Heads’s signing process after Dom0 updates.
We’re interested in making this FAQ publicly available and perhaps open-source for new contributions, but we’re not entirely sure of the best way and place to do so. On the one hand, it’s much more in the weeds than either the official documentation or the planned “Simple User Guide”; on the other hand, it would be unwieldy to manage as a set of “Guides” threads here. Just about the best idea we’ve had so far is to set up a Library site, at the cost of using Google Drive rather than GitHub as the system of record.
Do folks here have any suggestions, ideas, or wishes for how documentation like this can best come into circulation?
The Qubish thing to do would be to distrust the infrastructure. Github makes distrusting the infrastructure “easier” since commits are signed, your account has 2FA, etc. But that’s only if you trust Github (Microsoft) to actually commit your changes, or not leak your password, etc.
Perhaps a self-hosted git server might be a way to mitigate this? Or maybe the Qubes Team should be contacted when one wants to publish very detailed documentation, so there can at least be a notice on qubes-os.org that these various, other docs have (or haven’t) been reviewed for accuracy, integrity, or authenticity?
External documentation can be anywhere else (such as forums, community websites, and blogs), but there is an especially large collection in the Qubes Community project. […] If you’ve written a piece of documentation that is not appropriate for qubes-doc, we encourage you to submit it to the Qubes Community project instead. However, linking to external documentation from qubes-doc is perfectly fine. Indeed, the maintainers of the Qubes Community project should regularly submit PRs against the documentation index (see How to edit the documentation index) to add and update Qubes Community links in the “External Documentation” section of the documentation table of contents.
Sounds amazing, thank you for sharing it! It sounds perfectly suited to the Qubes community documentation project. I would recommend submitting it there.
Thanks, all. The wrinkle I’m coming up against is that I can imagine that some of our documentation might not be accepted to Qubes-Community/Contents, which would leave us able to contribute only selectively from our fork. But this feels like a much-bigger question of information architecture and tooling—how to “remix” documentation from multiple sources—to which I don’t expect you to have an answer. We’ll give this a try and see how it goes!
As explained here, we’re perfectly happy to see various external documentation sources flourish. That’s a sign of a healthy ecosystem. Qubes Community was just the natural first suggestion when you asked, since that’s where the bulk of external documentation resides.
No overwhelming or concrete reason, so much as deference to the team/community’s judgment on how much information to include about (e.g.) Heads, specific applications and setups, etc. But perhaps I’m overestimating the degree of curation within Qubes-Community/Contents!
Basically, our goals are:
to contribute as much of our documentation upstream and/or otherwise publicly as possible; and
to avoid maintaining our documentation in multiple venues and formats.
There’s no reason these goals will inevitably come into conflict. I’m just being transparent about anticipating that possibility—and trying to be sensitive to all parties’ limited capacity—before starting to contribute from a fork in earnest.
Hello, may I also have access to this documentation / repository? I am making some end user facing guides for specific use cases and I may be able to enrich some of your work.
I appreciate the interest my original question here seems to have generated, both publicly and privately. Rest assured that I’m not withholding this documentation. It will appear here once I’ve been able to get it into a publishable state.
