Notes about Qubes OS documentation(s)

Issues

Currently working on

• Add the community doc “How to open URLs/files in other VMs” to the official docs (still a lot to do!)

• Be clear about the exact release targeted by the documentation and its status (needs review)

• Improve the “Command-Line Tools” reference web page (needs review, there is more to do but not now)

• Remove ads from documentation (I need an answer from Marek)

• Collect all existing documentation and publish it, see also:

  • Create a sphinx doc for qubes-builderv2 and put it on RTD

  • Create a sphinx doc for qubes-app-linux-img-converter and put it on RTD

  • Create a sphinx doc for qvm-create-windows-qube and put it on RTD

  • Create proper sphinx docs for qubes-mgmt-salt and put it on RTD

  • Create proper sphinx docs for qubes-core-admin-linux and put it on RTD

  • Create proper sphinx docs for qubes-desktop-linux-common and put it on RTD

  • Add qubes-video-companion to Read the docs

Things to do

• Remove unused code related to :ticket: role in qubes-core-admin dochelpers

Issues about the structure / maintainance

• Provide a hierarchy in the How-to guides of the documentation

• Better integration between “How to use devices” pages and “qvm-device” documentation

• Add a way to review documentation pages

• Remove duplicated dependencies in qubes-doc

Build issues

• Offline documentation

• Orchestrate documentation build with disposable qube

Good ideas

• User-focused documentation of qubesctl/saltstack

Missing parts

• Document device “self-identity oriented” assignment in user documentation

Other things

• Confusing mention of “hard wrap” in the documentation style guide

• Clarify the “Verifying signature” documentation page to help users following it

• Visual Style Guide page was not migrated to RST and is not present in RTD

• Provide a decision tree for reStructuredText markup in docs

No one seems to care

• Read the docs search box is very laggy