Community-created Simple User Guide

Goal

Yet to be clearly defined. Community effort to create a simple user guide that can help new users learn the basics in a non-overwhelming way. (Think if it as a “Qubes OS for Dummies”)

Interested Contributors

Note: feel free to change / remove / correct your commitment at any time (it’s a wiki-post, you can edit it)

  • @HackerNCoder will (try to) maintain any images as part of his image mastery.

We need maintainers
As noted by the seasoned docs writer @adw, people tend to get all excited to produce new resources. But this has to be balanced with people who can commit to keeping this maintained.

Project Roadmap

1. General Outline :flight_departure:

Asynchronous workshop w/ virtual post-its

  • Tool: Miro or Pro Ideaflip
  • Begin: Ideation, anytime! Workshop in aforementioned potential tool, once moderation considerations have been established. (nina, tbd)
  • Requirements: maintainability
  • Completion: on solid group consensus on what it should look like

2. Drafting :spiral_notepad:

We make that a wiki-post and unleash the community

  • Tool: Forum wiki post
  • Completion: TBD (nominating an editor?)

3. Publishing :rocket:

We restart the conversation about where it should live, but this time with a concrete thing to look at and a team of contributors that have ownership and commitment to the thing. (quoting @Sven)

  • Completion:
    • Published somewhere
    • Having a list of maintainers & until when they commit

Bellow is the original post of this discussion (the above has been edited to keep track of the community project).

@adw generally tries to avoid documenting other projects (like XFCE). And here on the forum, when someone has questions about a particular subcomponent (XFCE, fedora, debian, etc.) I try to point people to fora of said projects. But newcomers to linux will never identify these things as “subcomponents” and in that sense it could be important to introduce Qubes as a system and not just a set of projects joined together.

I feel like in a sense the “Getting Started” page does already address some navigational issues, but maybe it could be more gradual, visual and have less geeky references that may steer newcomers away from reading such essential intro.

The customization part may fit the community documentation. There are some customization guides in the docs but only one of them is about the UI (enabling dark mode). We could add there the whisker menu guide.

4 Likes

Correct. Explanation: Documentation Guidelines | Qubes OS

All of this stuff absolutely should be documented, just not in the core Qubes docs. :slightly_smiling_face: However, we can certainly link to it from the core Qubes docs.

For example, if you use any search engine to search for “what is a linux distro,” I’m sure you’ll find many instructive pages.

Please actually do read this and don’t make me copy/paste it into this thread. :slightly_smiling_face:

1 Like

For example, if you use any search engine to search for “what is a linux distro,” I’m sure you’ll find many instructive pages.

Please actually do read this and don’t make me copy/paste it into this thread.

omg. Ok, I looked at it—and actually think we’re speaking to two very different needs. Hear me out. :slight_smile:

  1. The #1 rule of usability, is “Don’t make me think!” Requiring end-users to google things, imposes that upon them. More users will want a simple answer and to get on with their tasks, than to read any instructive pages—let alone be burdened with many. We may see a pupu platter of nourishing food, while many users will see a time and thought burden when they’re not interested in nor capable of either. Tangentially, to even compose the query “what is a linux distro” users must already have a mental model of Linux to understand that Linux is not “an operating system” but a type of operating system—like ice cream—with many flavors… and “distros” are those flavors built of ingredients that are “upstream projects.” I have friends who are Linux users, who still don’t understand any of that. That needs to matter, more, with QubesOS, because an important segment of our users are not Linux natives—and don’t use QubesOS out of “Open Source Afficianado” curiosity. FOSS is not a hobby for them, nor a lifestyle for them. They’re just activists, wanting to not go to jail, have their system destroyed by malware (and Qubes is the safest option to address both), or put money towards capitalistic greedy tech companies. Or, they’re poor and just can’t afford proprietary greedware. Yet their expectations for using ‘a thing’ are modeled by consumer products—they’re busy and want to focus on their work, not adopting a lifestyle. If we want to retain and attract those users, we need to bend from traditional FOSS practices, to accommodate them more. I want to attract and retain more of those users, personally, because QubesOS is not just Linux—it’s security and safety for activists, journalists, and many other non-nerdy folks. It’s also not Apple or Microsoft.

  2. The federated model of documentation makes a lot of sense for volunteer team execution and management. Unfortunately, it also imposes many burdens for the end-users consuming that documentation. One, it requires that users understand that when they buy “a laptop,” that not all the software in that laptop came from the same place. It’s already quite a disconnect for many, that they cannot get all (or any) of this information on the Lenovo website (as an example). That is how Windows and Macs have trained us to think. So then we expect them to grasp that, while QubesOS shipped and packaged this operating system they installed, Qubes doesn’t also provide docs for how to configure those things? Many of my journalist users already feel “highly technical” and superhero-ish, because they downloaded and installed an operating system that didn’t come with the machine they’d bought. Then they go to the QubesOS docs, and experience a hybrid of overwhelm and disorientation—ultimately choosing to text the people they trust to just provide an answer. :frowning:

When I buy a Specialized brand bicycle, I still get information in the owner’s manual for how to use and do basic things with my Shimano derailleurs and my Chris King hubs. If I want to take those things apart or do other fine-tuned stuff with them, THEN I need to refer to the “Service Manuals” written and published by those manufacturers—but basic/everday use, gets covered in the literature from Specialized that comes with the bike… because I’m a Specialized customer, and they want me to have a good experience. And they’re a multimillion dollar company that can pay entire departments to do nothing but make those materials, yes. That too.

Even friends of mine who use Ubuntu, will correct me to insist that they use Ubuntu, not Linux. So we’re expecting those folks to also understand that parts of their OS additionally come from different places, and to figure-out those dependencies? That’s fine for technical and academic users, but to mature away from serving exclusively FOSS enthusiasts, I’d like to do better. The owners manual that came with my truck didn’t tell me to go to the AC Delco website to get instructions for jumping the battery, or the Cummins website to see what kind of oil filter I need for the engine. Yet if I’d want to fix or modify things with the engine outside of routine maintenance, then I’d need to get a Service Manual from Cummins. Tire pressure is almost never put in owners manuals, but is instead printed on the tire walls themselves, because either the core vehicle will outlive the tires, or users will put on different tires to serve a specialized traction purpose… so if it were common for QubesOS users to also change their desktop environments, it’d make sense for us to not publish anything for an XFCE environment on the QubesOS website. Yet most users do keep “what was shipped” (XFCE), or didn’t understand the question on the survey (so didn’t understand the mental model we’re currently expecting of them).

The attrition rate for QubesOS is quite high, right now. That is not appealing to funders, and “poor documentation” was revealed in our survey as to a lot of the why. Qubes documentation is absolutely NOT “poor” by FOSS standards—it’s pretty damn amazing, actually (yep, people said that, too)! But for people not interested in FOSS as a way of life or as a dedicated hobby, and who simply want A Reasonably Secure Operating System, or to not go broke always paying GeekSquad to restore a compromised system, the docs are alienating and overwhelming, while also failing to offer the simple answers to things they are likely looking for (such as how to configure my desktop).

The page you linked me to, I opened—and it’s a massive wall of text. That, alone, is a discouragement. I appreciate how much effort was put into that text, but I “just want a simple answer.” I don’t want “to think.” I just want to be able to use my computer to do the things I got it to do. I want that to be more ok, for more of our users.

TL;DR, I think much of the problem, here, is that we don’t have a simple user guide that works for non-technical and non-FOSS users. I wish we did—or, were at least more open to shaping what we do have, to also serve that purpose. XFCE’s guides are overwhelming. I really, really wish what Deeplow put together, could go into a Qubes user guide. And yes, I’ve also talked Erik Moeller’s ear off (SecureDrop) on this same topic, for SecureDrop users. We’ve only not done the same there, because we don’t have the robust contributor community Qubes has, nor the core-team bandwidth.

There is a saying, that sometimes 80% of your users will only ever want 20% of the information an org publishes. QubesOS’ documentation is amazing for highly technical, deeply curious and patient users; early adopters, and developers. It’s a burden and not usable, for our most at risk users. I’d like to change that. Endless link-outs and burdening folks with how good or bad an upstream (XFCE) team’s documentation might be, isn’t a good experience. It’s pretty awful, actually. I’m advocating for an experience that’s both good, but also simply more “on par” with how consumer product models have trained user expectations. And, I know that Deeplow (and probably other contributors) would be keen to work on such materials, too. While I appreciate that “the federated FOSS approach” would have them do those things, self-host them, and then QubesOS simply link-out to them—thinking it’d be a good thing to give users a choice to pick which guide to use—that’s burdening folks with Yet Another Decision. Something “Official” and on the QubesOS website, and as dead-simple as possible—ideally validated with user testing, and written to much different standards of plain-language and minimal-text than what exists today, is what I’d personally like to advocate for happening. The “Simple User Manual” vs “The Bible.”

</daily-nina-rant>

6 Likes

The thing is, I “got started” last year. Again, it’s about information architecture and shaping a complete IA to fit user mental models. One size will never fit all, and expecting everyone to fit into the one size will discourage many. Docs can (and I feel, should) target specific user groups. The existing docs are amazing, for developers and existing Linux users.

Creating a “(simple) User Guide” and “(detailed) Documentation” as two separate entry-points, feels like a solution I’d like to work towards. Even developers and Linux folks could benefit from that, when they’re in “I just want a quick answer” mode, vs “I want to learn and get CLI snippets” mode.

My prototyping tool, UXPin, actually has some of the best docs I’ve seen in some time, for what I’d qualify as “A Basic User Guide.” For its audience, this is the ‘detailed’ user guide, though, lol. The volume of text it shows for each topic and the amount of details shown, are really what most users are willing to invest in on their own, before diving into a user community for support. Yes, as a power-user, I find this woefully inadequate—but for getting my head around the ins and outs of a complicated product, it’s perfect.

I never have to read more than about one paragraph at a time, to get the answer I need. That’s a result of really carefully plotting-out how the entire structure of the docs flows—what the “content buckets” are, etc., before composing any content—and then frequently adjusting as-needed, until the complete artifact is complete.

Nomenclature is user-facing and simpler than internal nomenclature, too. “Interface” as an example, sounds clearer to me for a QubesOS section about desktop tools, than “Desktop” or “GUI,” which is what would make sense to Linux folks. I suspect much of the language was determined by “Card Sort” exercises with end users. Looped inline videos in 5-second chunks to show basic tasks being executed, also really helps, as does showing UI components in the context of the whole screen—and then yes, up-close.

Disclaimer: I haven’t looked closely at contributing to the Qubes OS docs yet.

I do empatize, though, with the difficulty of keeping multiple bodies of documentation in sync when modular boundaries are crossed (e.g. the moment Qubes OS starts writing docs to cover features of XFCE that change on their own schedules). I’m also the first to advocate for ruthless-when-it-needs-to-be prioritization! That’s to say I think @adw’s focus on protecting the Qubes OS team’s time by keeping the Qubes OS docs focused makes a lot of sense to me and is essential to achieving any goal the Qubes OS team sets for themselves.

Yet I also believe that ensuring that Qubes OS is accessible to the people who need it is a goal that we can agree on as a community. Quick disclaimer again: I’m myself fairly new here and I certainly don’t pretend to speak on behalf of anyone but myself, but that being said I surely hope that it’s a goal we can broadly agree on!

And, like @ninavizz, I recognize that the extent of the people for whom Qubes OS offers security that few other tools would provide them (and who sometimes need it urgently) only partially overlaps with the group of people who are as comfortable with a body of modular docs (and as used to identify pieces as modular fragments of a whole) as some of us are.

So, thinking aloud. How might we experiment with what maintaining a more extended body of documenation looks like in practice, without over-burdening the Qubes OS team? (And how might we experiment with what the scope could be for that new body of documenation, so that we can find out for a fact if that’s sustainable?)

It seems to me, like @ninavizz noted, that there would be people willing to contribute to such effort. Assuming that’s true: would starting such an experimentent in the community docs be an acceptable compromise?

That certainly would require some coordination from the Qubes OS team, and certainly insight for scoping, would such an additional burden be acceptable/manageable now? What do you think @adw? (Not only on the effort estimate, but on idea of experimenting in the community docs in the first place? - I’m fully aware that I don’t see a full picture :slightly_smiling_face:)

1 Like

I also 100% agree with needing to ruthlessly protect the core QubesOS’ team time.

And, I know that @deeplow (and likely others) is very interested in developing more “Basic User Guide” type instruction for folks.

I love the idea of beginning such a project, at the community level—with occasional check-ins for accuracy, usability, maintainability, and other points, from the core QubesOS team. Enough to not be a burden, while also retaining some quality-control such that such a final artifact might be eventually adopted and published to the QubesOS website (where such an artifact would be most intuitively found and trusted).

I’ll also shut up now, as I’d love to hear what @adw and others think. Also, not in a rush to see this resolved at all. We’re all very busy. I just wanted to get it on the radar!

1 Like

[…] we don’t have a simple user guide that works for non-technical
and non-FOSS users. […] I really, really wish what Deeplow put
together, could go into a Qubes user guide. […] the robust
contributor community Qubes has, nor the core-team bandwidth.

Hi @Nina, I think virtually everyone here agrees with you including
@adw. His point I think is that the core developer team does not have
the bandwidth to deal with this (create & maintain) at this point in
Qubes OS’s development.

I know that Deeplow (and probably other contributors) would be keen
to work on such materials

You bet.

Something “Official” and on the QubesOS website

In my professional live I have ended countless philosophical arguments
by creating facts (i.e. prototype or draft) that could then be
criticized and improved upon. My proposal:

  1. You make a very rough very high-level outline

  2. We make that a wiki-post and unleash the community

  3. Once we have a first good result, we make it available exactly as the
    guidelines say we should.

  4. We restart the conversation about where it should live, but this time
    with a concrete thing to look at and a team of contributors that have
    ownership and commitment to the thing.

See also:

2 Likes

How might we experiment with what maintaining a more extended body of
documenation looks like in practice, without over-burdening the Qubes
OS team?

It already exists here:

But now with this Forum and it’s ability to have wiki-style posts
(everyone can edit, but with history) we have a new tool with an even
lower barrier to entry than GitHub.

Nothing is stopping us (the community) from creating what @Nina is
asking for and publishing it the way the guidelines call for it.

Once that is done, there will be a product and a team of people who feel
ownership and are committed to maintaining it. From there this could go
many ways including some community members becoming official
(documentation) contributors to the Qubes OS project. In any case this
conversation will be much more positive and fun once there is an actual
body of work to look at.

Besides that even if it’s not (yet) part of the “official”
documentation, the potential target audience could still benefit. Think
of it like a book written about a product but not published by the
company that makes the product. “Qubes OS for dummies” :wink:

2 Likes

But now with this Forum and it’s ability to have wiki-style posts
(everyone can edit, but with history) we have a new tool with an even
lower barrier to entry than GitHub.

Nothing is stopping us (the community) from creating what @Nina is
asking for and publishing it the way the guidelines call for it.

I had no idea that was a capability with the forum—huzzah!

Yes, Freedom of The Press Foundation’s training team has already put together materials for a “Qubes For Dummies” kind of training. Same, with Insurgo. I’m due to chat with Thierry at Insurgo about his training experiences, and will get some good additional insights from that. @deeplow is also endeavoring as his masters’ thesis, a “Qubes 101” sort of artifact.

If @deeplow would be keen to partner with me on this, and others on the core team and in the community would be keen to support the creation of such a resource, I’d be happy to volunteer to get an initial draft going in a few weeks. Paid work obligations, regrettably, stiffing my availability to work on such an artifact, until then.

Thank you for the cando/sodoit kick, @Sven!

2 Likes

Yep, thanks @Sven for your guidance. :+1:

@ninavizz @deeplow When the time comes to start putting these docs together, I’d be happy to help with what I can. (Taking advantage that my own getting started is relatively fresh :slightly_smiling_face:)

2 Likes

Amazing discussion here. Since it had gone way beyond the scope of the issue, I have split it into another discussion.

Comments / ideas from my dissertation

Well, to be frank I believe what Qubes really needs is a good onboarding. In my dissertation I’m working on an integrated onboarding tutorial, which does tackle a bit of this. But is way less resource efficient than any well produced guide or video. However, I’m constrained by the fact that I am in an engineering degree and making solely documentation would probably not appease the jury :sweat_smile: .

Non-gradual Documentation

I did some interviews with Qubes users and I also got people saying very good things about the documentation and others saying that it had not been useful to them at the beginning. (I should publish some of these results). One of the most insightful comments about the documentation was something along the lines of:

It is written from the perspective of “you know what you’re
doing”. And usually time that you look at the documentation is when
you don’t.

I’ve been there and I know what the user means. The documentation is really great as a reference material, but users have different needs at different times. So all the work invested by @adw and other community members into the docs were well invested and really appreciated! It’s just that there is also the need for another kind of educational resource.

Quoting from the phenomenal “Teaching Tech Together” book by Greg Wilson (can’t recommend it enough for those interested in user education):

The cognitive differences between novices and competent practitioners underpin the differences between two kinds of teaching materials. A tutorial helps newcomers to a field build a mental model; a manual, on the other hand, helps competent practitioners fill in the gaps in their knowledge. Tutorials frustrate competent practitioners because they move too slowly and say things that are obvious (though they are anything but obvious to novices). Equally, manuals frustrate novices because they use jargon and don’t explain things.

A while ago I was trying to visualize the links between documentation pages. I believe this visualization highlights the inter-dependencies of knowledge (i.e. traces of “reference material”):

If it were a gradual resource we would possibly a directed acyclic graph (i.e. links only to previously covered content). Something like the picture on the right. This would serve as a basis for what is called a “learning trajectory”.

Theory aside, all I mean to say is that I fully agree that there there is a need a more user-centered practical guide to Qubes that serves a different purpose than the documentation. And I think it could be a result of the community work.


Count me in!

Count me in! I’ve already made some initial work for my thesis in splitting up information into “lessons”, which could be useful.

As @sven pointed out, a wiki-post on forum may be a good place to draft such a resource (in the #user-support:guides). Apart from the side-by-side markdown visualizer we can also drag-n-drop pictures.

@gonzalo-bulnes I think insights on user documentation are very welcome. I first learned about the Divio’s documentation system on this issue you opened: https://github.com/freedomofpress/securedrop-docs/pull/141. And also, from you and other “fresh” Qubes users is of the upmost importance!

4 Likes

@Nina wrote:

Creating a “(simple) User Guide” and “(detailed) Documentation” as
two separate entry-points, feels like a solution I’d like to work
towards.

Maybe we can get the simple user guide done as a community project
without burdening the core developers?

@Nina would you give us a very rough outline structure of you think is
needed – nothing fancy, just a starting point so there is no blank screen?

We could make that into a Wiki-Post (everyone can edit, but we have a
history of all edits … just like on Wikipedia).

This would be an excellent way for everybody in the community to
contribute and also be a good learning and discovery experience.

Once we have a meaningful result, we could publish it on it’s own
website and link to it from the Qubes OS website.

Shall we try?

5 Likes

I have been hoping to do something like this myself so I’m willing to support this effort!

I’ve had some ideas myself for what sort of information would be helpful for newcomers.

2 Likes

I’ve had some ideas myself for what sort of information would be helpful for newcomers.

Do you feel like summarizing and posting your ideas to this thread? This
way we could collect ideas from you and anyone else who has them and
start discussing / fleshing them out.

There is no reason that our starting point has to come from @Nina. We
can take her input and merge it with whatever we already have.

Writing is always messy. Let’s collect all we can, flesh it out and then
discuss what/where/in which order. Nothing is wasted, as even parts that
might not end up in the “simple user guide” can be harvested and
contributed to the community documentation.

I think there are a lot of people who want to contribute / give back to
Qubes OS but don’t see themselves becoming Xen/Kernel experts or even
writing Python GUI code. But everyone who uses Qubes OS can contribute
to this!

One thing I can commit to right here and now: I will translate the end
result into German.

3 Likes

Please go ahead and summarize some ideas in this thread!

I honestly think the best possible starting-point output, would come from an asynchronous workshop… in a tool that allows for post-it-note fidelity-level rearranging of information in small bits. Bits that are visual and prevent participants from writing sentences upon sentences, or getting too granular into detail—and allow for easy moving-around of parts and creation of more parts. All of which can be visible at once. Which is why post-its on big blank walls are so delicious.

Most of my participation I think, should just be in moderation—as I am not a power user of Qubes, but am very aware of where non-Linux-native users have struggled in their adoption and learning curves. I’m also a UX practitioner by trade, and can setup some guiding principles and guardrails to guide others in actually “Creating” the goods. If that makes sense.

Once that workshop is completed and there’s a solid group consenssus around what a 10,000ft view should look like, drafting in a wiki can begin.

I posted this in the other thread, but will share again here as a reference point. In regards to how information is “bucketed” hierarchically, and nicely segmented into cognitively accessible bites—UXPin’s documentation is a good example I’ve been using a lot lately for the App Menu redesign project: https://www.uxpin.com/docs/getting-started/downloading-and-using-uxpin/

2 Likes

Unless you or someone else knows a FOSS solution, I’d be willing to sign up for a Pro account with https://ideaflip.com/ and invite you all as guests onto the board. I expect we will finish this first async workshop phase in 1-2 months top and won’t need the board after that.

1 Like

Whoops! I’ve had to do some weird merge of topics here as the discussion diverged into another topic which I only noticed after I had split the thread from the original discussion. But despite some posts not being in chronological order, I believe it hasn’t lost any meaning.

@sven in these situations you can keep discussing on the original thread (even if it’s no longer on the same subject). Just point out to me to split the thread like this user did here. Otherwise my merge-foo trickery doesn’t work so well :slight_smile: . But I appreciated the initiative! (also, I’ve given this topic the title of your other post).

For what is worth, I took a few notes before deciding to prioritize writing down my learnings on using Salt in Qubes OS.

I wrote those down before learning about the Divio’s documentation system that @deeplow mentioned above, and haven’t revisited them since I put them on hold. My intention was to move them to my public notes eventually, but as @Sven said: it’s often easier to start somewhere, so if those are useful I can move them (or any useful bits) to the forum.

2 Likes

Project Management

I’ve attempted to consolidate all the ideas for this project on the first post. I’ve also added there a list of interested contributors and roadmap for the project. I have made it into a wiki post so anybody can contribute.

Here’s a sneak-peek:

1 Like

Some months ago, I wrote a module for the German BSI IT-Grundschutz (IT Baseline Security Manual). The text is rather shortb and somewhat formal and mostly contains requirements on what to do or not to do in order to use Qubes in a secure way. It is still not officially published - the BSI is a governemt office and thus not too fast :slight_smile: -, but you are free to use any part of it that might be helpful. You’l find the text at the issue IT-Grundschutz Module for Qubes Client.

@Sven This text is already available in English and German.

3 Likes