Community-created Simple User Guide

After seeing @deeplow’s demo yesterday I think the right approach would be:

  1. collect use cases / scenario


    • intro to qubes / window borders / copy & paste / moving files
    • intro to templates / installing software / customize menu
    • intro to network / proxy qubes and simple firewall rules
    • etc
  2. write tutorial scripts to work with @deeplow’s project

The advantages are clear to me:

* interactive
* engaging
* short
* teaches the basics

Thank you @deeplow for getting this started – I believe it will make a
huge difference once implemented to it’s full potential.


I agree that the interactive guide presented by @deeplow is amazing and is the right approach. However, to me it also lacked the introduction which I mentioned. @deeplow actually showed that the two qubes are like computers but it was designed as a surprise in the end, whereas I suggest to make a user expect it. In such case, all suggested actions become clear earlier. What do you think?

I think it should not matter who the users are at this point, because the fundamental difference of Qubes OS from other systems is still the same: isolation.

Also, explaining how to copy files between qubes should not be the first task, because it is discouraged by the Qubes security model. I would let the users think that the qubes are independent first. You should allow interaction between them as rarely as possible.

IMHO, it always matters who the users are. But, that said, my thoughts when creating that mockup were that security engineers to super-nerds to journalists to curious retirees alike, would be sitting there after likely hours of work already invested in initially learning about “what this thing is” and then installing Qubes.

An icebreaker to help them pivot from “learn about & make it possible” to “use it + develop new habits and mental models” feels important. So, for all users, that was the sole purpose of this screen. In it I did want to speak to the colored borders, the naming conventions at the top of the windows, and the flood of notifications—soley because those are things people will initially “see.” Functional explanations, were intentionally limited to “how to turn internet on” and “how to open an app.”

A colleague and I were both sharing yesterday, that upon our first boot both of us just sat there and stared, giddy at our new Qubes laptops, totally stumped with what to do first—yet exploding with delight that we finally had This Really Cool New Thing we were hungry to put to work for ourselves.

Kind of like a person researching and then committing to skydiving for the first time. You do all sorts of work before you’re at the edge of the airplane door, but then once you jump out and you’re floating in the air at 20k ft above the Earth… a “do this next” cue is nice. :slight_smile:

Have I mentioned yet, btw, how completely excited I am by Deeplow’s work?

The “Community Created Simple User Guide” will be an excellent compendium, along with the richer and more technical official docs.

1 Like

It’s part of my dissertation. 6 users in total who were Qubes users and only perhaps three mention this (if I recall correctly). It’s not a large sample so one can’t really extrapolate. This could be a good thing to reasearch. Although I would be temped to look first at academic publications on the topic: do users use first or do they customize first?

Seeing for example from the fact that most uses keep the defaults (everywhere), I’d be inclined to think first people use the default compartments and then build upon them. So following that logic in the simple user guide could be a good idea. (assuming research backs my logic here).

Ah. Good idea!

I would agree. But I’m down for that synchrnous / asychronous activity to brainstorm more. Ideally we could build this upon the curriculum that Qubes trainers are using. They have the feedback loops that we’re missing. Sadly, I’m afraid there are not many out there.



I’m down for that synchrnous / asychronous activity to brainstorm

dito, but I realize that I am ignorant enough to require moderation and
guidance from @ninavizz … so I hope she can find the time to chair this

1 Like

@ninavizz wrote:

after likely hours of work already invested in initially learning
about “what this thing is” and then installing Qubes […] giddy at
our new Qubes laptops, totally stumped with what to do first—yet
exploding with delight that we finally had This Really Cool New Thing
we were hungry to put to work for ourselves.

Kind of like a person researching and then committing to skydiving
for the first time.

Yes. That’s what I meant when reaction to your and @deeplow’s comments

The “Community Created Simple User Guide” will be an excellent
compendium, along with the richer and more technical official docs.

What do you think about implementing the “Community Created Simple User
Guide” as tutorials? I realize that would make it a thing that needs to
be reviewed and integrated by the core team… but maybe that would be
worth it?

Maybe I am just too excited by what I saw yesterday.

As @Sven hints, this effort initially started out with the goal of creating a written piece of textual documentation, but it appears to be morphing into something that piggybacks on @deeplow’s integrated tutorial work. I don’t think that’s a bad thing, but it’s important to be cognizant of it and to pursue it intentionally. Personally, I think that we’ve been relying on the documentation to do too much for too long, and it’s high time we started integrating things in software that belong there far more than they do in documentation. Bravo!


I’ll find the time. Really, I promise.

Yes to all of this!

BTW @deeplow I did not want to clutter-up your GitHub issue for your tutorial, anymore than I may have already—but I did want to share with you this very rad tutorial I came upon today, that (of course!) had me think of you.

It’s for video recording presentation software (Mmhmm), intended for primarily Mac users and made by a UX consultancy, All Turtles. Susan Ferrel in the SimSec Slack is a design principal there, and I found out about the product there. Using it for my Summit talk—but also was quite impressed by the use of humans talking and pointing to areas in the UI, for a tutorial.

1 Like

Interesting. Qubes used to have this. See the archive here:

The issue with videos is that’s it’s very hard to update and maintain. Unlike plaintext. I recall a paper in which they presented library tutorials via video and via paper and found no difference in efficacy (can’t find the reference, though).

So the question is: do we want to have an intro video? Or should we keep it simple and do plaintext?

I’d be more inclined for plaintext, unless a community member makes a superb short intro video that is general enough to withstand the change of time (at least for a while)


Any content that is created, should be documented somewhere for lifecycle maintenance. Screenshots, plaintext, and video, all are equally suceptible to neglect. Which then, community mods pay the price for, with taking community wrath.

Agreed, videos are both harder to localize, and to update.

Content Strategy is an important part of UX, but also requires… well, the time of humans. Which is far from infinite, in volunteer efforts. As we all know.

Yes, when millions of dollars fall from the sky, definitely we need video tours. I am with you, until then, tho.

1 Like

Is this project ongoing? I would love to contribute feedback to any draft that exists. Great idea!

1 Like

Given the goal of “create a simple user guide that can help new users learn the basics in a non-overwhelming way”, you may want to look at: Contents/ at master · Qubes-Community/Contents · GitHub , which had the goal of helping someone new to using qubes answer the question “Do I want to use qubes / Can I live with using qubes?”

It’s 2 years old now, and hopefully thunderbird will work someday (which could replace the mutt section), but it’s available there if anyone wants it, or wants to use it as a starting point for new documentation.

AFAIK Thunderbird works, I wrote a guide for using it with Protonmail: Guide: split-Protonmail (offline send/receive qubes + pm bridge vm)

Thanks, but I was referring to the thunderbird issue: Rewrite Thunderbird Qubes extension as a MailExtension · Issue #5861 · QubesOS/qubes-issues · GitHub which is still open.
Specifically i was referring to the ability to open attachments in a disposable, and to open a link in a disposable, which is what I believe the (non-working) thunderbird qubes extension does.

But as explained in the comments on that issue, you can (right now, today) configure your setup to open attachments and links in disposables without the extension.

Interesting. Thanks!

To anyone wondering, the answer apparently was:

There is the option to add common file types (PDF, Office formats etc)
to the “Files & Attachments” preference in Thunderbird and hook it to
qvm-open-in-dvm. That works just as well as thunderbird-qubes did for me
especially in combination with the ‘ask’ policy.

1 Like

Hi there, I made a post in general chat about this very thing. If you are willing to talk me thru some things I would be happy to make video tutorials that should be able to get noobs like me up to speed rather quickly. I am considering doing it myself but the problem is that in learning how to fix my problems thru the provided documentation I am going to lose the noobyness that will allow me to make tutorials that will be plain and clear to noobs. I have watched the tutorials available online and they all sound like they are talking in french to regular users like me. I have litterally spent hours unpacking a single sentence only to discover that I did not need to know any of it really other than to understand how to something that ultimately took five minutes to get working once i cut thru the jargon and information only useful to someone that wants to play around in the terminal for fun.
But I do plan on making a tutorial for the things I have figured out that other noobs will probably give up when facing. For example the time it took me to sort out the partitioning of my drive to install the qubes was difficult due to me not being a linux user when all I really needed to know took five minutes once I knew what I was looking for. A noob could look for information for awhile before discovering that the qubes installer is basically the same as other well documented distros. The videos on cubes assume they are speaking to distro hoppers that already know all about linux when in reality the noobs like me look at the partitioning phase and think holy crap this looks complicated and feels like one wrong move could destroy my drives. I now can explain how to safely partition in less than a minute haha.
But yea What I really need is someone that can tell me what I am looking for, like what piece of the puzzle is where I should start to solve X problem that people are use to windows just doing for them.
But I agree with what you are saying, we should not want to live in a world in which some whistle blowers need to be computer scientists to feel comfortable enough to survive long enough to even blow the whistle. I personally have information I want to get into the right hands but cant even begin looking for the people that can use the info until I can be confident it will not be discovered and covered up because it easily could be covered up. Tails is easy to use but is not an efficient means to do the needed research one needs to do to find the people that the courage and the reach to use certain information. Well sorry for the wall of text and here is the post I made if you want to read another one.

This sums it up well I believe. I am a fast learner with an almost genius IQ and coming from windows to qubes has made me feel extremely stupid. I am documenting my journey and plan to make video tutorials that will tackle the problems as they arise to a typical human.
For starters it appears as though you can not even make a bootable usb for qubes on a windows PC. I tried a dozen times on three different PCs and every time I would try to install I would get an error that said “can not install qubes without installing the linux kernel.”. I had given up when a few days later the thought popped into my head that maybe to save space or something the iso pulled the kernel from the PC when the bootable usb was made which cant be true and sounds ridiculous but I got that funny feeling and installed Kali linux on an old laptop and downloaded the iso and made a bootable usb and it worked the first time.
Great I thought so lets rock. All was well until until I got to the disk partitioning and hit another wall. This looks complicated and dangerous if I make a mistake. Struck with decision paralysis I started to look for information on the qubes install and partitioning process. Hours and hours later I discovered that the installer was basically the same as the Debian installer(whatever the hell that is) and within 5 minutes I was back to installation.
Now I am stuck at trying to get my raid drives to be usable and I have the feeling that it will take five minutes to fix once I know what information I am even looking for. I am currently reading pages and pages of documentation on LVMs as the first sentence of the guild to set up slave drives starts by saying assuming you have already set up your LVM… I expect after several more hours of fishing around I will solve the issue and be able to guide someone else thru the process in a matter of minutes.
The good news is the next problem I get to solve has documentation that for the love of god I hope will be simple to follow and absorb. I have not looked yet because I can not bear the thought of it being another rabbit hole of jargon to unpack before finding an answer that could be expressed in a few sentences.
But year I am documenting my experience and plan to make a simple how to to get the average user thru the very basic stuff required to make qubes a functional OS. It looks worth the trouble but it couldnt be more obvious that the people writing the documentation have no idea what a regular windows user is going to have to deal with when switching to Qubes OS. This is kind of surprising since most people in a position to blow the whistle on the government or evil corporation are going to be coming from a windows background…

He is my thread if anyone is interested in volunteering to help me out, If I can get it sorted out I would love to help others never have to go thru this.

Might be relevant: AnarSec Qubes OS Guide