Improvement of the Introduction Page

[luzeal]

The problem you're addressing (if any)
The Introduction to Qubes OS page could use some deep refactoring.

• As of now, it seems the intro page targets users with almost no prior knowledge of computers or information security. To me - I may be wrong - Qubes OS is not intended for people that are new to operating systems. It is not something I would recommend someone to install on their first computer. Quite the contrary : to me, it is intended for people who are familiar with the command line and with Linux in general, or at least people that are ready to accept a steep learning curve.

• Because the page seems to target beginners, I believe that people with more prior knowledge will find the introduction page quite dry, at least until they scroll down to "How does Qubes OS provide security?". For instance, there is no mention of the Xen hypervisor until the very end. What Qubes is made of ? One may not know until looking at the documentation. (On the Qubes OS main page, there is a mention of the section "What's Inside of Qubes". It may be a good idea to replicate it in the Qubes OS intro.)

• To me, at present, the introductory page does not serve well motivated beginners nor advanced users.

Describe the solution you'd like
I intend to rewrite the page to make it less verbose and more straight-to-the-point, to add one or two diagrams and to caption them, and finally to move unessential parts to the FAQ.

By adding a diagram that has the right level of abstraction, and is accurate, it will still help beginners and advanced users to understand what Qubes OS is made of, and to introduce most of its concepts. An analogy will also be drawn.

Where is the value to a user, and who might that user be?
It will benefit both advanced and beginner users, and hopefully will help to give potential new users the right level of information right off the bat so they will better know what to expect.

Describe alternatives you've considered
I haven't considered any alternatives. I believe it needs to be rewritten, but I am open to how it should be done.

Additional context
I will do the rewrite in the context of the Season of Docs (SoD) project. Rather than to take a deep dive in the documentation, I thought it made sense for me to focus on the introduction page, because it is one of the primary entrances to the rest of the project, and also because it was flagged as a project idea for SoD by a Qubes member. Also, as the page is quite symbolic and important, it makes sense to me to do it early to let the community and team members have enough time share their contributions.

Relevant documentation you've consulted
I have consulted most of the Qubes documentation including the [FAQ page].(https://www.qubes-os.org/faq/)

Related, non-duplicate issues
I haven't found one related to the introduction page.

[luzeal]

I know it is not how it is probably supposed to work, but rather than creating a pull request (A process which I am not yet particularly comfortable with (by the way, where should I store pictures?), I paste my first rewrite for the page here :

What is Qubes OS?

Qubes OS is a free and open-source security-oriented operating system meant for single-user desktop computing.

Qubes OS allows you to compartmentalize various parts of your digital life into compartments. If one of those compartments get compromised by a malicious email attachment carrying a ransomware, others parts of your system will remain unaffected : this is one of the key benefit of the security by compartmentalization approach taken by Qubes OS.

Illustration by Lydia Greve, to be vectorized.

Working legend : You can think of Qubes OS as a cargo ship, whose water-tight compartments and hull can sustain a certain damage threshold. Typically, on such a boat, a breach in one of those compartments won't result in the sinking of the entire ship. The same applies to Qubes OS : various parts of the system may be compromised without affecting the integrity of the entire system.

How does Qubes OS enforce isolation?

Behind the scene, Qubes OS leverages virtualization and more specifically the open source Xen hypervisor to allow the creation and management of well isolated virtual machines called qubes. Those qubes, which are also referred simply to as domains or compartments, have specific :

• Purposes : for personal or professional projects, to manage the network stack or else.
• Nature : full-fledged or stripped-down virtual machines which can be based on Fedora, Debian or even Windows.
• Levels of trust : from complete to non-existent.

Another distinct features of Qubes OS is that as a user, you are free to use, copy and modify it. In other words, Qubes OS is a free and open source software. The source code, including the documentation, is openly available so that others can contribute to and audit it, which we strongly encourage you to do !

Why Qubes OS ?

A traditional OS works this way :

Upcoming legend

Qubes OS works that way :

Upcoming legend

The diagram is heavily inspired by this one. Rutkowska CC BY SA NC

[andrewdavidwong]

A few quick comments:

• Thank you again for doing this!
• It will be much easier to provide feedback if you open a pull request, since we will be able to make in-line comments. Here's a guide: https://www.qubes-os.org/doc/doc-guidelines/#how-to-contribute
• There are a lot of little grammatical errors in this draft. I suggest having a copy editor go over this.
• It's important to understand that the use of Xen (and even virtualization in general) is merely a contingent property of the current implementation of the Qubes architecture. Qubes itself is independent of the compartmentalization mechanism used. For more on this, see: https://blog.invisiblethings.org/2013/03/21/introducing-qubes-odyssey-framework.html

[luzeal]

Hello Andrew, thanks for your feedback ! I have finally created a pull request. My first draft has been copy-edited by a native speaker. As for your last comment, I understand that virtualization could be replaced by something else to enforce Qubes OS security model, and that as a result, one may not want to emphasize this technology in the introduction page. However, Qubes OS, understood as the operating system you can download from Qubes OS website, is heavily relying on virtualization and I want to describe that version, not the whole project. (Otherwise, we may need to introduce a distinction between the project or architecture itself from one of its implementations, which happens to use Xen). There is some documentation available on Xen. If it's true that one can consider the current Qubes OS implementation as a Xen distribution, then I believe it might be useful for users to know that it actually relates to Xen so they can use existing documentation (the same is true of Fedora.).

[marmarta]

I love the pictures and ideas here! I'm thinking that a good direction to go with that would be creating something that can also be shown to the user at first boot - so that a user that just had installed Qubes would have any idea of where to go next (conceptually). I'm currently working at making a tool to facilitate first boot and using Qubes for nontechnical users, and I'm thinking this would be a great fit.
@luzeal , would it be possible for you to make a html page - or a PDF, or anything, really, whatever you're comfortable with that looks nice - that would be based on the ideas you have here, but geared towards explaining the Qubes model to someone who's thinking "okay, I installed this thing... now it asks me about personal and work and what are those things? how many of them do I need"? I'm thinking about adding a button with "Introduction to Qubes" to my in-progress config tool, and the thing that would be great would be having something simple, and yet clear to show when it's pressed.

[andrewdavidwong]

Related: #1774

[luzeal]

Thanks for your feedback everyone. I am trying my best to send the last changes before the end of Season of Docs, but I am struggling : for instance, I don't know how to blend markdown and HTML well (and I am afraid I am not following the guidelines perfectly...)

Anyway, I have added the diagram. Should the source of it be stored to allow further editing ? (SVG).

I am sorry I won't have the time to follow @marmarta or @andrewdavidwong's take on the intro. Those are great ideas for another small project.

[luzeal]

[luzeal]

FYI : I am working on the project report for Season of Docs. I don't expect my work to be incorporated before the end of the project (in two days!), as it will require more back and forth.

[luzeal]

Related pull request : QubesOS/qubes-doc#900

[deeplow]

@andrewdavidwong It seems this one can be closed.