Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve non-technical intro #6698

Open
deeplow opened this issue Jun 14, 2021 · 18 comments
Open

Improve non-technical intro #6698

deeplow opened this issue Jun 14, 2021 · 18 comments
Labels
C: doc C: website P: default Priority: default. Default priority for new issues, to be replaced given sufficient information. T: enhancement Type: enhancement. A new feature that does not yet exist or improvement of existing functionality.

Comments

@deeplow
Copy link

deeplow commented Jun 14, 2021

Note: This may or may not be a hard sell for the Qubes team. After all, it's about hiding a lot of the technical accomplishments from the second page. However, I feel like it's a necessity if Qubes wants to diversity its IT-majority userbase.

Affected component(s) or functionality

Page https://www.qubes-os.org/intro/

Brief summary

Qubes aims to support vulnernable non-technical and power ones alike. However, the first part of the introduction page is focused mostly on the technical aspects. This is the "pitch" page for why one should use the product.

Non-technical users may be scared away by this or not understand the value.

Expected behavior

Not scaring away potential non-technical users.

Actual behavior

  • many technical terms like
    • virtual machines (VMs)
    • network stack
    • firewall
  • levels of trust diagram confuses people
    • I have received feedback that read the intro page expected compartments to be trust-level based, but then they are presented with personal and work qubes, which don't follow this. So it is ambiguous advice.
    • Shows the high-level architecture of the system. Something a non-technical user may not care about (at least on the introductory level).
  • No image of what the system is like

Screenshots

Current state:
introduction2

Additional context

Solutions you've tried

Not really tried, but a proposal:

  1. Move the current contents of /intro into /technical-intro

  2. Re-create the /intro page with less technical-descriptions, starting with the Why Qubes? (leaving the How? for the technical intro).

  3. Adding a note on /intro for technical users:

    Are you a technically inclined individual? Learn here how Qubes works under the hood.

Relevant documentation you've consulted

Related, non-duplicate issues

#6694

@deeplow deeplow added P: default Priority: default. Default priority for new issues, to be replaced given sufficient information. T: bug Type: bug report. A problem or defect resulting in unintended behavior in something that exists. labels Jun 14, 2021
@andrewdavidwong
Copy link
Member

First of all, I welcome and applaud your efforts to improve things. I just wanted you to know that. Here are a few general thoughts:

  1. The current intro page is the relatively-recent result of a Google Season of Docs project, the sole focus of which was to revamp this very page (Improvement of the Introduction Page #5357, GSoD project). Now, not all GSoD projects work out, but it would be a bit sad if that project turned out to be a waste of time. Nonetheless, all we can do is look forward and try to improve things from where they currently stand.

  2. It all depends on the goal of this page. What are we trying to accomplish with it? As you said, "This is the 'pitch' page for why one should use the product." That's certainly one possibility, perhaps even the most likely one. If that's the purpose of this page -- to convince readers that they should use Qubes -- then the focus should be on persuasion. I'm not really sure how to convince non-technical readers that they should use a security-oriented operating system, but I don't doubt that it can be done.

  3. As a somewhat technical person, I personally find that a lot of websites for stuff that should be technical are just fluff, and it's rather annoying. So, I've developed a sort of calibrated BS meter that I use to filter out all the nonsense products, projects, and companies. I know that I'm not alone in this. Many other technical people are the same way. If I were to see something that advertises itself as a secure OS, I'd immediately be skeptical and want to know, "Why should I believe that claim?" If I then go to the website, and I don't see anything technical to back up that claim, I'd infer that they're probably just another bunch of charlatans with no real security expertise and just a marketing team trying to peddle the usual snake oil. There are so many scammers and fakes out there that legitimacy is a rare and valuable commodity. It's also one we happen to have in spades due to our amazing developers. The last thing we want to do is hide it. So let's just be careful not to hide the technical stuff too much. I think your suggestion of having and linking to a technical intro should take care of this, as long as it's not easy to miss.

In general, though, I agree that this would be a good idea.

@andrewdavidwong andrewdavidwong added C: doc T: enhancement Type: enhancement. A new feature that does not yet exist or improvement of existing functionality. and removed T: bug Type: bug report. A problem or defect resulting in unintended behavior in something that exists. labels Jun 14, 2021
@andrewdavidwong andrewdavidwong added this to the Ongoing milestone Jun 14, 2021
@ninavizz
Copy link
Member

+1 to @andrewdavidwong's comments of appreciation and gratitude for all the thought you put into usability for Qubes, @deeplow!

My own take, is that I generally don't feel that there should be two different sets of instructions for a product—one for extremely technical people, and one for extremely not technical people.

Highly technical concepts need to be able to be explained in the simplest of terms—overlooking all the nooks and crannies and nuances—at the outset of any user engaging with them. In a section qualified as "Basics" or "Overview" or something else like that, more advanced users are simply being obnoxious to develop expectations of exactitude, when broad-stroke comprehension is a clear goal.

#5357 resulted in an awesome "Introduction" page. For using a technical tool, however, a lot of very different knowledge needs to be consumed and retained. The key to that sentence, being "And Retained." The Xen architecture is irrelevant, in the context of "Inform a person the ins-and-outs of how to function within this thing." The benefits of compartmentalization, is also a different topic.

The "Introduction" page is not a "How to use this thing" page, though. That needs to come from the "User Documentation" section—yet that header is not inviting to people unaccustomed to consuming FOSS documentation. That needs to matter.

The beginning of the "Common Tasks" section, is introductory text to learn about how to use Qubes. Yet the header "Common Tasks" does not map to where users' heads are at when they need to consume that content. That needs to matter much more, than an encyclopedic accuracy of content bucketing. This isn't an academic textbook. This is a place people come to learn.

There is no reason it should be super technical. The more guides we have, the harder it is to both maintain them all, and to keep users focused. So, I still really want to improve the "Common Tasks" section along usability principles for learning, to better navigate people into Qubes.

A benefit for all of us, I would like to have happen, is fewer questions in forums. The user attrition rate right now for Qubes, is also just too high.

@ninavizz
Copy link
Member

Separate but related: the artifact created by #5357 is not intended to be consumed by people about to use Qubes OS. Its purpose is not to guide use, but to inform a decision about whether or not to use Qubes OS.

Once a person has committed to using Qubes, their entire perspective about taking-in information about Qubes, shifts. The initial "vetting" process to commit to a technology, begs many questions other than tangibly "Ok, I've chosen to commit to this—now how do I use it." That question, is even different from "How can I meaningfully use it."

The goal of #6694 is to slowly build capacity in a user's learning memory.

@SvenSemmler
Copy link

SvenSemmler commented Jun 14, 2021 via email

@andrewdavidwong
Copy link
Member

My own take, is that I generally don't feel that there should be two different sets of instructions for a product—one for extremely technical people, and one for extremely not technical people.

One idea to avoid this is to just have one non-technical introduction and move the technical stuff into a "technical overview" that basically lists the technical merits of Qubes for technical people who want to know our bona fides. It might even make sense to expand and use https://www.qubes-os.org/doc/architecture/ and/or https://www.qubes-os.org/security/goals/ for this purpose.

@DemiMarie
Copy link

My own take, is that I generally don't feel that there should be two different sets of instructions for a product—one for extremely technical people, and one for extremely not technical people.

One idea to avoid this is to just have one non-technical introduction and move the technical stuff into a "technical overview" that basically lists the technical merits of Qubes for technical people who want to know our bona fides. It might even make sense to expand and use https://www.qubes-os.org/doc/architecture/ and/or https://www.qubes-os.org/security/goals/ for this purpose.

I like this approach. We could have the introduction end with a statement like, “If you are wondering how Qubes OS works, you can find a technical overview here. If you are a developer interested in hacking on Qubes OS itself, documentation on how to do that is here.”

@GWeck
Copy link

GWeck commented Jun 15, 2021

There is already a quite good not so technical introduction at https://www.qubes-os.org/doc/getting-started/, but it is not easy to find it from the current introduction page (just one or two links which are not very obvious).

@andrewdavidwong
Copy link
Member

There is already a quite good not so technical introduction at https://www.qubes-os.org/doc/getting-started/

But it's not a pitch page. See above. Also, @ninavizz doesn't think it's very good. See #6694.

but it is not easy to find it from the current introduction page (just one or two links which are not very obvious).

How is it not easy to find? There's a large "Getting Started" subheading with a big button that links to the page. What more should be done?

@GWeck
Copy link

GWeck commented Jun 15, 2021

You're right, there is that button - but: It's deep down on the page, and so I didn't find it first time, and I suppose that will happen to other users, too.

Leading users a way that they learn the important pieces fast is a very tricky business, especially if technical and non-technical users both have to be addressed, like it is the case for Qubes. And already, the Qubes documentation is in this respect far better than most of what you get in the Linux and Windows world!

The current introductory page has two big areas, describing the What and the Why, the first addressing more the technical folk and the second more the non-technical users, as far as I see it. How could we lead each type of users to the section most appropriate for them? This could help to ease or even solve the problem tackled here.

@deeplow
Copy link
Author

deeplow commented Jun 15, 2021

How could we lead each type of users to the section most appropriate for them? This could help to ease or even solve the problem tackled here.

I think this a general overarching problem we have to tackle here. I like the following approach as well

One idea to avoid this is to just have one non-technical introduction and move the technical stuff into a "technical overview" that basically lists the technical merits of Qubes for technical people who want to know our bona fides. It might even make sense to expand and use https://www.qubes-os.org/doc/architecture/ and/or https://www.qubes-os.org/security/goals/ for this purpose.

I like this approach. We could have the introduction end with a statement like, “If you are wondering how Qubes OS works, you can find a technical overview here. If you are a developer interested in hacking on Qubes OS itself, documentation on how to do that is here.”

So in generally, addressing the why one would use Qubes. Potentially with some use-cases / personas. And then leaving some links to the "How?". This way these would not be two different sets of instructions and the great work put into #5357 would keep its value.

Kicked off a related discussion here: https://qubes-os.discourse.group/t/how-to-pitch-qubes-os/4499?u=sven

@SvenSemmler I quite like this idea of an elevator pitch. Already some great ideas there Let's see where it takes us.

  • As a somewhat technical person, I personally find that a lot of websites for stuff that should be technical are just fluff, and it's rather annoying. So, I've developed a sort of calibrated BS meter that I use to filter out all the nonsense products, projects, and companies.

@andrewdavidwong I know what you mean. I feel the same. Qubes is characteristically "reasonably honest" about security marketing ;) and I really like, as a technically-inclined individual. Let's then try to keep this property while also managing to give the user good information about if Qubes is the right tool for them while not getting into too many implementation details.

@ninavizz
Copy link
Member

How is it not easy to find? There's a large "Getting Started" subheading with a big button that links to the page. What more should be done?

You should pair with me in a user research session sometime. :)
Users look for headers that align with how they identify their needs—not how we may categorize their place in the arc of Qubes knowledge access. That's the magic with content design (eg, the words we pick) for documentation.

How could we lead each type of users to the section most appropriate for them? This could help to ease or even solve the problem tackled here.

"Leading" is bad. Marketers do that. I suspect everyone in this Issue fears the marketing boogey-talk. :)
Intuitive navigation for users is not always what makes topical sense, in encyclopedic thinking of information. I think we're off to a FAR stronger/better result than I could have ever expected, when I filed the initial issue that initiated this avalanche of goodness.

Just having this discussion to separate what is "Learning to potentially adopt" vs "Learning to use;" user engagement/outreach vs user learning/retention, is so important.

@deeplow
Copy link
Author

deeplow commented Feb 2, 2022

@ninavizz I was not sure where to give you feedback on the prototype, so I'll put it here.

Homepage feedback

I like the idea of adding making the download button less prominent. If someone already wants to install it, they'll know where to click. I would make the download button a link instead and the question a button.

Screenshot 2022-02-02 at 13-22-24 Qubes OS A reasonably secure operating system

But I have a feeling those who come to the website may mostly want to answer the question why use qubes?

Screenshot 2022-02-02 at 13-23-33 Qubes OS A reasonably secure operating system

Introduction page (Overview)

On the prototype this is the overview. As argued above, the current introduction is a bit about the How. But the why seems more important. So instead of making two versions of the intro page (a technical and a non-technical), I'd suggest the page have the following sections:

  • Why Qubes? (se bellow)
  • How it works (the current intro page)

As for what to include in the why Qubes? I'd suggest finding the 3 to 5 top "why" use-cases and adding them there. This should work for both user-groups without overwhelming novices.

I made some assets for the tutorial, which I ended up not using. They could be useful here. Let me know if you're interested @ninavizz

start

@andrewdavidwong
Copy link
Member

But I have a feeling those who come to the website may mostly want to answer the question why use qubes?

Perhaps this should be directly on the home page rather than requiring the visitor to click through.

@deeplow
Copy link
Author

deeplow commented Feb 3, 2022

But I have a feeling those who come to the website may mostly want to answer the question why use qubes?

Perhaps this should be directly on the home page rather than requiring the visitor to click through.

Yes. That would be my preference as well.

@deeplow
Copy link
Author

deeplow commented Sep 21, 2022

This was discussed during the Qubes Summit. @marmarta, @mfc, I and some others brainstormed about how we could talk about what Qubes does in a non-technical manner.

Goal: have a visual metaphor of what Qubes does. (inspiration: how Tails works)

The idea would be not to re-do the introduction page, but rather put this in the homepage, such that when the user clicks on the "Why use Qubes" button they get scrolled down to a part where it explains what it is and what it does.

@marmarta
Copy link
Member

Notes/initial writeup of that simplified "Why Qubes is great" site from the mentioned brainstorm (also thanks for the ping here, @deeplow )

Don't compromise on your security and privacy
[image: needs ideas]
Qubes OS allows you to control your security and privacy and not be at the mercy of application developers.

  • you decide which qubes can access which devices
  • you can easily create single-use qubes (disposable qubes) that disappear after use and cannot compromise the rest of your system accidentally
  • you can control how data moves between qubes, copying files or clipboard data only when you want it

Organize your life
[image: map with different separated places]
Qubes OS allows you to better organize different parts of your life: work projects, private life, potentially vulnerable activities such as banking can all exist in completely separate spaces.

  • keep separate areas of life in separate qubes
  • control access: decide which qubes can access which devices
  • you can get the security of multiple separate computers without having to own and maintain multiple machines

Backup and restore what you want
[image: boxes packed for a move/ boxes put in locked storage while someone's travelling?]
Qubes OS has a flexible and powerful backup system that allows you to easily make encrypted backups of all or parts of your system.

  • you can only backup the qubes you need to backup
  • easily restore the parts of your system you need

Take control of how you access the internet
[image: boxes sent over mail?]
Qubes OS allows you to control which qubes can access the internet and how - directly, over VPNs or Tor, or maybe only to certain IP addresses.

  • easily manage multiple networks (Whonix/Tor, VPNs, direct internet access)
  • control how website see you

@andrewdavidwong andrewdavidwong changed the title [docs] De-technicalize "Intro" page (and move it to "technical-intro") Improve non-technical intro Sep 22, 2022
@deeplow
Copy link
Author

deeplow commented Sep 28, 2022

Idea: having transitions

This might be overkill and perhaps require javascript (not totally sure) but it would be amazing if we got one of those fancy scroll things like this

move-like-this

So the transitions could be something like this:

  • Control your security and privacy
    3 qubes colored laptops, side-by-side, each with a similarly colored orthogonal qube on them

  • (transition) qubes move closer together and turn into card boxes

  • Organize your life
    A character shows up bending over the boxes and sorting colored objects (with the qube's colors) and putting the blue notepad in the blue box (work), the yellow postcard in the yellow box.

  • (transition) boxes go into a house-moving truck or boxes packed for a move/ boxes put in locked storage while someone's traveling

  • Backup and restore what you want

  • (...)

@deeplow
Copy link
Author

deeplow commented Oct 4, 2022

But I have a feeling those who come to the website may mostly want to answer the question why use qubes?

Perhaps this should be directly on the home page rather than requiring the visitor to click through.

ipfs.io does just this

ipfs-how-it-works3

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
C: doc C: website P: default Priority: default. Default priority for new issues, to be replaced given sufficient information. T: enhancement Type: enhancement. A new feature that does not yet exist or improvement of existing functionality.
Projects
None yet
Development

No branches or pull requests

7 participants