qubes-doc
qubes-doc copied to clipboard
QubesOS
Update faq.md
Hey Andrew—this is kind of a lot. Trying to get some of the basic changes to existing-but-unclear or outdated questions, into incremental PRs. No rush. Curious what your thoughts are!
- Updated "What is Qubes?" to more clearly speak to less technical users, and users unfamiliar with OSS norms; while also providing a clearer answer to the specific question.
- Separated speaking to Qubes' FOSS status, as its own (following) question.
- Moved "How is Qubes different from other security solutions" up in the list
- Moved "What about other approaches to security?" up in the list
- Killed "Why does Qubes use Xen instead of KVM or some other hypervisor?" question, because it refernces the 0.3 architecture spec—which, even if that information is still correct, feels horribly out of date.
- Killed "What about safe languages and formally verified microkernels" question, as it directs to an article composed in 2010 for Qubes 0.3
- Killed "What is the concept behind Qubes" as it's redundant with "How does Qubes OS provide security?" (both speak to security by compartmentalization)
- Killed "Could you please make my preference the default?" as answer sounds scoldy... and, imho anybody asking that in a reciprocal community space doesn't deserve a response. I also do want people to ask those things in user research or surveys (so, w/o expectations of reciprocity).
- Updated XSA answer (near line 201), as current one points to a broken link, and to better adhere to UX best practices for FAQs and content writing (Don't simply give users an answer to link to another page, w/o first giving them a TL;DR high-level response where they expect one. Referring users simply to a link, frustrates folks).
- Edited answer to Passwordless Sudo (near line 247) for same UX best-practices reason cited in XSAs answer.
- Edited section name "Users" to "Using Qubes" (near line 319) as "Users" is not an intuitive section name for end users to identify their needs with. Will that break things, Andrew?
- Re-worded multi-user system question to speak more to how less-technical people model that question in their own heads (eg: only nerds or IT people think of this concept as "multi-user system." Will also help SEO for people wanting to discover this question with Command-F
- Added (near line 372) new question to speak to governance idea Andrew proposed, of only speaking to version-specific compatibility between things, in the actual Docs
Oops—meant to include this link in the first (I think): https://en.wikipedia.org/wiki/Hypervisor Currently there is a placeholder in place of the actual link.
Killed "Why does Qubes use Xen instead of KVM or some other hypervisor?" question, because it refernces the 0.3 architecture spec—which, even if that information is still correct, feels horribly out of date.
But why ignore correct information just because it's "old" (which just means it's remained true for a long time)? From that perspective, the study of history has no value.
In this case, other parts of that document are actually outdated, and we've decided to delist it from the doc index, so it makes sense not to reference it, but that doesn't mean the entire question has to go, just the reference. This does still seem to be a frequently-asked question, FWIW.
Killed "Could you please make my preference the default?" as answer sounds scoldy... and, imho anybody asking that in a reciprocal community space doesn't deserve a response. I also do want people to ask those things in user research or surveys (so, w/o expectations of reciprocity).
I have to link to that one fairly often. Sometimes people deserve to be scolded, but I'd be fine with toning it down. "Doesn't deserve a response" simply doesn't work with some people. They'll assume they're right and we're just too lazy or cowardly to respond (because deep down we know we're wrong and they're right). This emboldens them to beat the drum louder and make my life more difficult. No thanks.
Updated XSA answer (near line 201), as current one points to a broken link, and to better adhere to UX best practices for FAQs and content writing (Don't simply give users an answer to link to another page, w/o first giving them a TL;DR high-level response where they expect one. Referring users simply to a link, frustrates folks).
In theory, I agree, but in practice, offering just a link is the lesser evil compared to content duplication. This is a general point about the documentation as a whole. Ideally, we would have modular blocks of content that could be dynamically included in various places, but that would require a lot of work, and we're not really set up to do it right now.
Edited section name "Users" to "Using Qubes" (near line 319) as "Users" is not an intuitive section name for end users to identify their needs with. Will that break things, Andrew?
Probably. Have a look at the CI log to see.
One non-technical thing it breaks is the parallelism between "users" and "developers," as well as introducing a gerund while the other headings at this heading level are not.
Oops—meant to include this link in the first (I think): https://en.wikipedia.org/wiki/Hypervisor
Currently there is a placeholder in place of the actual link.
Go ahead and update the placeholder.
One non-technical thing it breaks is the parallelism between "users" and "developers," as well as introducing a gerund while the other headings at this heading level are not.
This is one thing I will push back on. Folks don't think through language on webpages like that; words either resonate with them, or they don't. That's a big tenant of usability; to design how users really think. Rationally and irrationally. I don't believe the word "users" is as easily recognizable to non-techies, looking for guidance... whereas "developers" will resonate with developers.
I don't know what a a gerund is. Would you prefer if I change developers to "Development" or something else to better align with "Using Qubes"?
In theory, I agree, but in practice, offering just a link is the lesser evil compared to content duplication.
Dig, will revert!
I have to link to that one fairly often. Sometimes people deserve to be scolded, but I'd be fine with toning it down.
Good lord. Yeah, making your life easier is the goal with much of these! Ok, I'll re-write the answer and the question, both, so it more clearly speaks to what happens in those situations, without also discouraging honest feedback in the context of user feedback when it is sought. Which is not in the places you encounter it (whereas in surveys or user interviews, it's totally desired).
But why ignore correct information just because it's "old" (which just means it's remained true for a long time)? From that perspective, the study of history has no value.
In this case, other parts of that document are actually outdated, and we've decided to delist it from the doc index, so it makes sense not to reference it, but that doesn't mean the entire question has to go, just the reference. This does still seem to be a frequently-asked question, FWIW.
Because that had been my takeaway as your guidance from my question yesterday in Wire? :D
My only goal, is to keep out-of-date information out of the FAQ. Is your suggestion to then amend the question to simply In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface). ??
I'll do a copyediting pass for language style and mechanics when merging, but here's my content feedback for now. Thanks for your willingness to help improve the FAQ! 🙂
One non-technical thing it breaks is the parallelism between "users" and "developers," as well as introducing a gerund while the other headings at this heading level are not.
This is one thing I will push back on. Folks don't think through language on webpages like that; words either resonate with them, or they don't. That's a big tenant of usability; to design how users really think. Rationally and irrationally. I don't believe the word "users" is as easily recognizable to non-techies, looking for guidance... whereas "developers" will resonate with developers.
I don't know what a a gerund is. Would you prefer if I change developers to "Development" or something else to better align with "Using Qubes"?
I see what you're saying. I'd just prefer to maintain a consistent pattern, all else being equal, like "Using Qubes" and "Developing Qubes" (although the latter sounds a bit odd), and we still have that weird "General/Security" section, so maybe it's too hard to find a consistent pattern at this level.
This is more of a stylistic preference, not a deal-breaker.
I have to link to that one fairly often. Sometimes people deserve to be scolded, but I'd be fine with toning it down.
Good lord. Yeah, making your life easier is the goal with much of these! Ok, I'll re-write the answer and the question, both, so it more clearly speaks to what happens in those situations, without also discouraging honest feedback in the context of user feedback when it is sought. Which is not in the places you encounter it (whereas in surveys or user interviews, it's totally desired).
What if we just remove the last sentence or two?
But why ignore correct information just because it's "old" (which just means it's remained true for a long time)? From that perspective, the study of history has no value. In this case, other parts of that document are actually outdated, and we've decided to delist it from the doc index, so it makes sense not to reference it, but that doesn't mean the entire question has to go, just the reference. This does still seem to be a frequently-asked question, FWIW.
Because that had been my takeaway as your guidance from my question yesterday in Wire? :D
I thought you asked about a different question rather than the KVM vs. Xen one. Anyway, I think the principle still holds. Correct information = good. Referencing outdated docs = bad. We can preserve the former while avoiding the latter.
My only goal, is to keep out-of-date information out of the FAQ. Is your suggestion to then amend the question to simply
In short: we believe the Xen architecture allows for the creation of more secure systems (i.e. with a much smaller TCB, which translates to a smaller attack surface).??
Something like that, yeah. Unless, of course, this turns out to be too brief of an answer to be useful, in which case we could remove the entry, but I suspect we'd end up writing a new answer and adding it back later (after receiving that question too many times and not having an easy answer to link, which is why we added it in the first place).
Bah! I just posted an update, with a long new answer to the "Make my preference the default" question.
My goal with the new answer, is to provide insight into why it is lame for folks to make those requests—as it's been my own assumption from emails I see and survey responses, that people just expect everything gets made like Mac and Windoze systems do. Preposterous and obviously ridiculous as that might seem to us (tho you personally have earned yourself a Lambourghini with your Qubes contribs, and then some!).
Super curious to hear what you think! I also really do not want to discourage folks from responding with honesty, where appropriate. Those channels did not exist before, and now they do. Not sure how much that may matter tho, just guessing. And I respect that you're the one who has to take the brunt of the selfish bozos.
I see what you're saying. I'd just prefer to maintain a consistent pattern, all else being equal, like "Using Qubes" and "Developing Qubes" (although the latter sounds a bit odd), and we still have that weird "General/Security" section, so maybe it's too hard to find a consistent pattern at this level.
(Users vs Using Qubes) This is more of a stylistic preference, not a deal-breaker.
All of these changes, for me, are incremental changes working towards an improved design for the page itself. With that updated design, I'm hoping to have more categories, and separate categories for "General" and "Security." So, I'm not at all married to making the "Users" to "Using Qubes" change, now. Whatever you're comfortable with, I'm happy to go with.
Mostly just trying to make some easy and incremental changes, with this. I leave it to your calls, from here! Unless you'd prefer to put anything back in my court, in which I'd be happy to oblige.
Oh, I think you missed my inline comments. I'm not sure if GitHub wasn't displaying them to you because I didn't submit/finalize the review earlier. (If so, my bad. Or GitHub's UX's bad.) Anyway, they should be visible now.
Spoke with @ninavizz about this PR. I'm going to try a revision soon and see how it goes.
Do you want further comments deferred until that revision?
Up to you. I welcome any comments that might help with writing a better doc.
@unman Apologies for the exclusion, by doing a phone call with Andrew. Andrew is an expert wordsmith, and I am an expert OMGIWANTALLTEHTHINGS-smith. It really helped hearing his feedback on my writing, after I shared with him my goals in composing the blurbs I had. I'm also not an async-native worker, so the telephone voice conversation and hearing one of the most articulate writers I've encountered on GitHub speak in verbal conversation (he speaks in distinctly Western American accent, with "like" as every-other word) and with a ready laugh, was strangely soothing. :)
We also discussed a strategy that could well work better for my interests in seeing writing to address both user concerns I observe in survey responses, and user-centric/ux-best-practice needs, here. So, I'll be writing issues, mostly, for written content, going forward.
You also have a much stronger grasp of writing mechanics, than I do—and I love your writing contributions. And, you have a direct connection to many of Qubes' users, that I do not. :)
@ninavizz, @unman: If you have any general feedback on the revisions I've done so far (first three entries), it might be helpful to discuss it now, before I get too much further.