Community-created Simple User Guide

I bet somewhere in this post there is a:

Divide Documentation into “How To.” “Why To.” “Consequences of not doing.”

If user can not make up his mind, “Do this (Nudge Notes).”

I agree with the idea of getting documentation for Journalists. Guessing they are not a highly computer technical audience, know enough that they should be afraid. And only want enough documentation to use Qubes without creating a hazard to themselves, their informants.

Look I have created a whole new level of confusion.

3 posts were merged into an existing topic: On offering GPG key for contact (trust level 2 required to join)

Quick question - I would like to get started on documentation but don’t know where to begin as I have never done anything like this before. Where and how do I get started? Thanks.

Started on improving existing Qubes documentation, or started on putting together a “Simple User Guide” discussed in this post?

I somewhat dropped the ball 9 weeks ago, offering to put together an asynchronous workshop and then just being perpetually too overworked to dedicate time to that. I still want to do that, but also don’t want to roadblock others excited to contribute to something, now.

I feel there are a few main points around which to orient this work, that should be defined up-front:

  • Who is this for (needs, motivations, existing skills)?
  • Who is this not for (needs, motivations, existing skills)?
  • What principles do we desire for content to align against?

After or in parallel to that, I’d suggest drafting an outline of topics to then write documentation against.

After or in parallel to that, if there’s a topic you feel excited to just dive on into, go for it!


A post was split to a new topic: How to Contirubute to the Docs?

I totally understand.

This is one of the blocking factors that keeps me at this moment stalled. For example - what assumptions do have for who this is for? Basic Linux knowledge? Perhaps a few month’s of Ubuntu usage as a base “profile”?

For the second and third considerations - I have no concept.

For my part, I would like to contribute to the Simple User Guide primarily as I would like to contribute to the easing what was a rather rough onboarding experience that I had when I went through teaching myself how to Qubes. There were places were the documentation was out of date or did not exist. And I had to teach myself through trial and error, sometimes breaking my install and starting over.

There is power in pain so I do not want all things to be simple but where it makes sense - there should likely be a doc to light the way.

So back to practical matters - I believe your workshop would hold considerable value but if one has to wait perhaps one can start here? Getting started | Qubes OS

1 Like

If I may:

What I envision is a short, crisp introduction to the core concepts of
Qubes OS. We can assume the user is familiar with basic UI concepts
(windows, dialogs, applications, mouse). The stuff a “non-technical” Mac
or Windows user would understand.

A recent thread makes clear that even things like a clipboard may
already need some more explanations.

The guide should explain the why and the how from a user’s perspective.
Why would I want to use Qubes OS? What is compartmentalization and how
would I use it? What is a qube, template, dom0? How do I exchange
information between qubes? How do I find and install additional
software? Where do I go to ask for help?

What the guide should not be: a discussion of underlying technologies or
products (virtualization, storage pools, Xen, Linux, XFCE bla bla bla).
One doesn’t need to know those things to use Qubes OS.

The target is any person wishing to take measures to secure their
information. We should not assume anything else. They can read and they
know how to use Mac or a Windows PC. That’s it.


Thanks for this. I’ll start drafting something and see what others think. Might be a week or so.


Aaah, thank you for jumping in with this, Sven!

The only additional thing I’d add @corbeaucrypto, is that, yes, I would absolutely include within this, people new to Linux. Why? The few folks I know who use Linux systems out of financial necessity (vs nrrdtasticness), have no idea what a “desktop” or a “desktop” environment is; don’t know what a “distribution” is, and also don’t realize the have a virtual potpourri of utilities at their fingertips should they choose. “I just use Ubuntu, and that’s Linux—right?” Folks working in non-profit, mostly, fit that category; folks largely using web-based tools, and MS Office products—who feel fancy knowing that Libre Office is a solid FOSS alternative to MS Office, as an example.

So, breaking-down the Linux ecosystem in its own article, feels like a good component to this. It’s just stopped-cold, many of my own attempts at discussing Qubes with Linux folks, when I realize they just have no idea what I’m talking about. To understand a multi-environment system, folks need to have a solid understanding of how single-environment systems work. Mac? Big walled-garden. Windows PC? Same. Linux, we have choices—but those choices require some really simple foundational knowledge, to meaningfully act upon.

Also, when I say “include ppl new to Linux in this,” I don’t mean infantalizing all Linux concepts throughout the guide. Only crafting one article to break all of this down within, and then making that article readily discoverable through click-paths from glossary items and other articles. Maybe I should volunteer to write that article, come to think, lol. Definitely no time commits from me on that, but happy to own it on my volunteer plate. Or, to let someone else excited to take a jab at things, go for it!

1 Like

Are you sure that such an article doesn’t already exist? I mean, it’s not like we in the Qubes OS community are the first to discover Linux. :slight_smile:

Perhaps we can balance the Qubes Docs philosophy of non-duplication through introducing certain concepts of Linux within the context of Qubes. I started using Slackware 20 years ago (mon dieux, time flies) and I find that very little of the Linux Way is actually needed to effectively run Qubes at the user level. Most frequent command I use? Apt-get by far. I think a minimalistic touch here would be in order. The rest can be covered better by others.


But that doesn’t even apply here, because this is a community guide. The intention behind this question was not to try to impose any policies on anyone. Rather, I’m trying to help you all avoid duplication of labor and reinventing the wheel. Just trying to help.


It’s a disjointed experience to be linked-out to external articles. As a mater of practicality and sustainability, for the “official” Qubes documentation, it would be akin to building a bomb, to not link out to external articles as often as possible. For a user-friendly community guide, I’m fine writing something short and sweet. Yes, I’ll absolutely look for something already written—but for getting users adept to Qubes, the learning burden is already quite high. I’m fearful of opening The Linux Can Of Worms, when the only point of introducing Linux concepts is to ground users in an understanding of the ecosystem, as it is foundational to Qubes. Not to get folks excited to customize things and experiment, or to learn about how/why OSS is so different from proprietary OS. If that makes sense. External links should be nice to haves, not required, in the best possible experience scenario.

As a non-Linux native, really, the most critical things for me were simply understanding the “pieces” of an OS. In Mac/Windows, it’s all seamless. In Linux, it’s helpful to know what “a desktop” is, distinct from the core OS; what “bios” are, that “File Managers” and “Print Mangers” and “Audio Managers” are all helper apps that sometimes ship with a distro, and can often be replaced with alternate versions; what “a distribution” is, and how some distributions are core distributions (Debian, Fedora), while others are adaptations of the core distributions (Ubuntu, Mint). Stuff like that.

None of that is fancy, just very foundational.

1 Like

Sorry Nina, I completely disagree on this: actually I agree with you
about not linking out, but disagree about almost everything else.

A simple user guide does not need to introduce any of these concepts.
Based on my experience, none of the things you’ve mentioned are
foundational in using Qubes. I mean, a new user can become at ease with
Qubes without knowing any of that stuff, as you’ve presented it.
File Manager, Print Managers, Volume controls - these are all familiar to
users coming from Windows.(I’m surprised that they aren’t familiar to a
Mac user.)
What new users want to know is how to do things. They need not know
anything about the underlying concepts of Qubes.

Here’s an example - users who have been moved to working from home don’t
need to know anything about RDP, internet protocols, VPNs and so on.
What they need to know is that they can start this program, enter their
normal login, and then they can see their desktop at work. Most users
wont go further than that.
It’s the same in Qubes - most users want to know how to do things as
they normally do, and that’s working at a very basic level.
I’ve said before that I think the users on the Forum are not
representative, either of current or intended users: I think that a scan
of the questions would confirm that.

1 Like

In my personal story of learning Qubes - not understanding the relationship between the TemplateVM and AppVMs slowed me down at the outset. And required me to read the docs.

I see Nina’s point coming into play when one starts to do anything beyond a basic build. There’s a transition from a basic desktop that requires one to start reading documentation and lack of familiarity with those concepts becomes a barrier to comprehension. But proper basic documentation may alleviate the need for an introduction to those concepts in good time.

For me - knowing those things was important when I needed to do something that the documentation, either through topical or temporal reasons (like being outdated) failed to address directly. I am not really an advanced user, in my mind, with Qubes. I have my AppVMs, my VPN, my devices - and it all works. I have done a few tricky things like porting over HVMs from OVA files into Qubes but nothing too terribly sophisticated beyond that. Does that help? Maybe in that it’s a use case that being an advanced user is not necessary for successfully running Qubes every day.

And frankly, a lot of the existing documentation really helped with that. The things that really challenged me 18 months ago when I got started was actually getting going. It took me three install attempts to get things right. Is that the usual story? I don’t know.

In a lot of ways - that experience is what is informing my notional view of how the guide will start. Once I get something produced - we’ll have plenty to discuss there I imagine.

I see three distinct areas:

  1. Getting it installed

    → we will be addressing this with a list of computers that can
    install the current release without any intervention in addition to the
    ‘certified’ options. I’ll compile the first version in the next days.

  2. Setting it up

    → this is the part where one needs an understanding of qubes specific
    concepts and how to apply them (domains, templates, proxy VMs etc.)

    —> this is where you either have someone who does it for you or you
    read the docs and ask your way through using the mailing list/forum. The
    docs are good, but to few read them.

  3. Using it

    → that’s where I agree with @unman fully. Once a Qubes OS system is
    installed and setup it’s basically a normal desktop with a fancy
    clipboard and colored window borders. A 2 minute speech about what those
    mean and pretty much everyone should be good to go.

I think 1 & 3 are things easily addressed by efforts already started.
It’s (2) that’s the big deal: how to enable the person who has no one to
help them and who has a hard time with the existing documentation and
asking for help on the forum?

1 Like

In theory, we could have an “easy mode” ISO where, once you install it, everything is already set up for you with sensible default programs and settings. The problem is that many users, constitutionally incapable of leaving well enough alone, would start to tinker with the defaults in an effort to customize things. They’ll immediately be back to square one in terms of needing to understand at least the basics of how Qubes works. The fundamental problem is that users have two conflicting desires: the desire to have a bespoke system that works for them, and the desire not to have to endure (what many see as) the mentally strenuous and painful process of learning things.

(Strictly speaking, this conflict of desires is not unavoidable. As you note, one could hire an expert to set up a Qubes installation to one’s specifications and gently spoon-feed the answer to each question that arises, potentially avoiding all the pain of learning and, with luck, escaping real understanding entirely. But this isn’t a practical option for most users.)

Of course, in practice, the “easy mode” ISO would likely never get off the ground, because there would be endless debate about what exactly the default programs and settings should be, with all sides lobbying for their personal favorites, paralyzing and dooming the undertaking long before it ever made it into users’ hands. :slight_smile:

1 Like

I believe most users will do it the other way around. From the few user interviews I did (part of my master’s dissertation) many referred the default config as a good starting point (and I did the same). Setting things up probably only happens after the user probably has the hang of the system.

So I suggest it being “2. Using it”, “3. Doing your own compartments” (or sth like that).

1 Like

I believe most users will do it the other way around. From the few user interviews I did (part of my master’s dissertation) many referred the default config as a good starting point (and I did the same). Setting things up probably only happens after the user probably has the hang of the system.

So I suggest it being “2. Using it”, “3. Doing your own compartments” (or sth like that).

I wonder who these users were, and where you sourced them?

As to the idea that users are “constitutionally incapable of leaving
well enough alone”, that certainly seems to be true of users in the
Forum. As I have said, I do not think they are representative.

It’s true that some users of any OS will fiddle to such an extent that
they break things. But not all.
Many users simply don’t behave like this.
Of course, in a corporate environment, there are strict constraints on
what users are able to do - in Qubes, we cant simply enforce this at

But there are users of Qubes who don’t behave like this, and don’t fiddle

  • in my experience these are users for whom Qubes is important.

This discussion seems quite complicated but impractical without a specific example to discuss. @ninavizz provided a great starting point in the Github issue:

To me it looks like a good start which could be improved and discussed. What it lacks in my view is a two-sentence introduction about what Qubes OS is all about: security through isolation. I would start with this:

Welcome to Qubes OS!
You now have independent colorful computers (“qubes”) inside your computer, each can run independent normal apps. One typical way to benefit from that is to use personal qube for your private tasks, work qube for work-related things and untrusted qube to open untrusted websites and files.

(Harsh) criticism of my approach is welcome.

Also, a link to these forums is really important as was already pointed out. Newcomers can ask any questions and get things done without hours or reading the manual.