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. 
-
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.
-
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. 
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>
However, we can certainly link to it from the core Qubes docs.
)
.
. But I appreciated the initiative! (also, I’ve given this topic the title of your other post).