Notes about Qubes OS documentation(s)

This is my personal “roadmap”: things that I want to improve.

Biggest issue: image accessibility

See also

email sent to qubes-devel

The way Sphinx and Docutils treat images and links has many flaws. When an image is inside a link without any text, the alternative text should describe the link function, not the image. So even with non-empty alt, that’s not a good situation. It is of course worst with empty alts.

Todo

raise that issue on Sphinx (or Docutils?)

Snippet for fixing this issue:

from sphinx.application import Sphinx
from sphinx.builders.html import StandaloneHTMLBuilder
from sphinx.util.typing import ExtensionMetadata

from docutils import nodes

import posixpath


class FixStandaloneHTMLBuilder(StandaloneHTMLBuilder):
    name = "html"
    html_scaled_image_link = False

    def post_process_images(self, doctree: Node) -> None:
        super().post_process_images(doctree)

        for node in doctree.findall(nodes.image):
            if not any((key in node) for key in ("scale", "width", "height")):
                # resizing options are not given. scaled image link is available
                # only for resized images.
                continue
            if isinstance(node.parent, nodes.reference):
                # A image having hyperlink target
                continue
            if "no-scaled-link" in node["classes"]:
                # scaled image link is disabled for this node
                continue

            uri = node["uri"]

            parent = nodes.paragraph("")
            reference = nodes.reference("", f"Link to {node['uri']}", internal=True)
            parent.append(reference)

            if uri in self.images:
                reference["refuri"] = posixpath.join(self.imgpath, self.images[uri])
            else:
                reference["refuri"] = uri

            node.parent.append(parent)


def setup(app: Sphinx) -> ExtensionMetadata:
    app.add_builder(FixStandaloneHTMLBuilder, override=True)

    return {
        "version": "0.1",
        "env_version": 1,
        "parallel_read_safe": True,
        "parallel_write_safe": True,
    }

Tips to contribute

Specific issues

Currently working on

Add the community doc “How to open URLs/files in other VMs” to the official docs

That’s a real mess… See: Rewriting of “how to copy and move files” + expansion of “How to edit a policy”

Be clear about the exact release targeted by the documentation and its status

Clarify the name of the doc and current version needs review

Improve the “Command-Line Tools” reference web page

Partial fix (Expand the list of available tools documentations) needs review, there is more to do but not now

Todo

At internal refs???

Remove ads from documentation

I need an answer from Marek

Collect all existing documentation and publish it

See also:

Things to do

Build issues

Good ideas

Missing parts

Waiting for a review

Other things

No one seems to care

General issues

I encounter various issues while contributing to the docs, affecting the ease of the contribution, maintenance burden or quality of the output. Some of them might be related to the history of the project?

Missing (cross-)references

In their current state, the docs are poorly cross-referenced. And when you try to change this, it’s a rabbit hole. I frequently want to refer to a command, an option, a RPC element, a service, etc. The problems are:

  • where is the reference for that? Sometimes it is split across various documents (i.e.: RPC policies). I feel like I won’t be able to fix this because this one is up to the devs or the experts, who are already busy with other things.

  • how can I link to that? I would like to be able to just type qvm-copy, qubes.OpenInVM, etc.). Potential solutions:

    1. create inline internal targets to reference something without having to do much more work

    2. make any the default role. There will be issues, as the default role has been used as a way to display literal code. Probably other issues too? That way, we don’t have to remember if qrexec is an option, a term, a reference, etc.

    3. autolabels are sometimes convenient but the sections you want to cross-reference are frequently used more than once. Also, for manpages it would be useful to have the command name as a cross ref on the page title.

    4. we can introduce a new “QubesOS” domain with custom directives and roles: :policy:, :service:, :event: (already in Welcome to core-admin’s documentation!)

  • what is exactly the definition of a term (i.e.: “Qubes RPC”, “qrexec”)

Quick references that I generally need but doesn’t exist:

  • programs (qvm-...)

  • RPC services (qubes.ConvertPdf)

  • prefs

  • features

  • services from qvm-service

  • RPC policy syntax (@default, etc.)

Typical issue related to this: Better integration between “How to use devices” pages and “qvm-device” documentation

The structure of the docs

The index is just a list of links

I would like a better homepage for the docs: with the main points highlighted before the full toctree.

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

The documentation was originally thought as something small without any hierarchy. It’s becoming more and more difficult, especially with the how-tos. I tried to see if we could create such a hierarchy but it doesn’t seem to be compatible with the navigation menu…

The FAQ

The FAQ is outdated and hard to read. Try to play with the contents directive.

Take a look at issue #7005 and link from @ninavizz: Strategic Design for Frequently Asked Questions

Diátaxis

I frequently use Diátaxis as a way to focus on the writing of a document. The map is very good, easy to follow. I really would like to engage a discussion about this, our documentation is much more easier to understand with this ideas in mind.

Using Diátaxis concepts, we can see that the tutorial part is almost totally missing from the docs.

Building skills in the docs

Currently the docs are very descriptive for even small actions (opening the app menu). Providing a reference for such actions could help to shorten some pages. I tried to help with that by introducing How to enable a qube service and How to edit a policy.

Most of those topics should be discussed as a whole to provide clear directions for contributor like me. I would like to have some kind of draft for a new index (with missing parts), etc.

About the quality / freshness of the docs

Add a way to review documentation pages

It has been discussed,

Remove duplicated dependencies in qubes-doc

This is quite annoying: more difficult to maintain.

A way to test the docs?

Sphinx can test the code snippets but how about having a way to test a how-to?

Create openqa tests related to a how-to? That would be very difficult to maintain?

Checking CLI tools consistency

Would it be possible to use sphinx inventory as a way to check the manpages?

Keep screenshots updated

This is the documentation of an OS, as such, we might need far more tools than the regular docs. Screenshots also get outdated quite quickly. @ben-grande worked hard on this for the docs about disposables. I think that one solution would be to use OpenQA to get them. I haven’t figured out how to get a precise screen from a serie of pictures (the 49th one, displaying the correct screenshot could become the 46th in another test run).

Somehow related: Improve supportive images of GUI in documentation

See also

“More automated qubes-doc screenshots” on qubes-devel

I suggested to use OpenQA on qubes-devel and got no answer (I need to check if it makes sense!)

Add and use a new qubes-doc-update-icons tool

An automatic way to retrieve pictures from qubes-artwork… @marmata left a comment about this, ironic?

SVG template

for editing a screenshot in a way that allows maintainers to update the screenshot while keeping the shapes on top of it?

Warning

This need to be user friendly. HOW?!

Tracking updates / better release notes for Qubes’ users

I miss so much the excellent contributions from @alimirjamali, especially the newsletter. From time to time I discover an improvement, that could be part of some release notes and that might need a screenshot update…

Current release notes are not meant for end users.

@marmarek advice is to follow:

Improve supportive images of GUI in documentation

Todo

proposal to use a SVG template with a grammar of shapes, texts, etc. using the original screenshot embed and CSS styles for consistency. Maybe override the SVG attributes to allow only a limited set and keep things consistent? SVG is editable in all sorts of editors, from a text editor to a browser, including Inkscape.

Unify contributions

Unified markup

We need to unify the restructuredtext markups across all repos. I encountered this issue will trying to help @ben-grande on the rewriting of the documentation about disposables. Some ideas:

Unified build process

It is possible to use submodules in qubes-doc to build all the docs at once in one repo. We can also share a common conf.py base.

Ideas that needs to be tested/discussed or raised as issues/PR

Accessibility in Qubes OS

New pages to provide basic informations. It is the 2nd item in the First steps section of the Tails documentation.

An index could be useful?

See if something is possible with Index

Asciinema for basic CLI operations

Using the command-line is very difficult for a lot of beginners and, unfortunately, it is mandatory for some operations. Like sudo dnf/apt install. nihalxkumar presented the qvm-template-upgrade tool with Asciinema and the result is very interesting. See: https://asciinema.org/a/1262072