Refactoring the intro page #871
Conversation
What I have tried to do is condense the page and remove information that I believe is a better fit for the FAQ page. If a comparison is still needed ("How does Qubes OS compare to XYZ"), I suggest a table rather than an entire section. Also, a section on : is "Qubes OS good for me" might be a good idea. Finally, a diagram will eventually be incorporated.
Update intro.md
There was a problem hiding this comment.
Thanks!
The text has been copy-edited.
There are still quite a few errors. Here are some examples (limited to the first two sentences):
free and open-source security-orientedget->getsa ransomware->ransomwareunaffected : this
The style and diction also leave a lot to be desired. I suppose we could ignore these matters for now in favor of the content, and I can do a final pass at the end.
This also doesn't follow our Documentation Guidelines, e.g.:
- One sentence per line.
- Relative paths.
Regarding the content: This seems like largely the same introduction as before, just with less information. So, yes, it's briefer, but I don't get the sense that it does a better job of introducing someone to Qubes who has no prior knowledge. It's pretty full of jargon and terse statements that a novice probably wouldn't understand.
I was expecting a novel approach. For example, maybe we begin by acknowledging the prospective user's security concerns, then discuss how having a bunch of separate physical computers would address them. But that would introduce new problems (bulky, expensive hardware; unsecure data transfer between machines), so we introduce Qubes as a way to have those separate machines virtually. Then the various features make sense: Of course you need colored window borders so that you can tell domains apart (just like you had to tell your separate physical machines apart). Of course you need qvm-copy, because it's solves the unsecure data transfer problem you had in the bunch-of-physical-machines scenario. This is just one example of a possible alternative approach.
Another might be introducing common workflows. You explain how most people do online banking, then point out the numerous security problems with it (same browser as random web surfing, same OS environment as untrusted app installation, etc.). Then you cover how you would do online banking in Qubes, explaining our unique features along the way. They're already contextualized, so they make sense. You immediately see the practical need for each one. Of course the banking domain has to be securely isolated from the untrusted browsing and work domains, and so on. Again, this is just one among many possible alternatives. Which is the most effective?
I'd like to see this approached more systematically: What goals should the introduction achieve? Once we've clearly articulated those goals, we can evaluate any proposed intro by seeing how well it satisfies them. Similarly, what are the problems with the current intro? If we can articulate those problems, we can evaluate the extent to which any proposed rewrite avoids them.
The first rule of good writing is to write for your audience. Who is your audience? What do they know? What do they desire? What are their priorities and goals? Which things do they not care about? How many audiences do you have, anyway? Are you trying to persuade them of something? (If so, what?)
introduction/intro.md
Outdated
|
|
||
| Qubes OS allows you to compartmentalize various parts of your digital life into isolated domains. If one of those compartments get compromised by a malicious email attachment carrying a ransomware, other parts of your system will remain unaffected : this is one of the key benefits of the [*security by compartmentalization*](https://www.qubes-os.org/faq/) approach taken by Qubes OS. |
There was a problem hiding this comment.
"If one of those compartments" -> "If one of those domains"
introduction/intro.md
Outdated
| Behind the scenes, Qubes OS leverages virtualization and more specifically the [open-source Xen hypervisor](https://wiki.xen.org/wiki/Xen_Project_Software_Overview) to allow the creation and management of well-isolated virtual machines called *qubes*. Those qubes, which are also referred simply to as *domains* or *compartments*, have specific : | ||
|
|
||
| * **Purposes** : for personal or professional projects, to manage the USB or network stack. | ||
| * **Natures** : full-fledged or stripped-down virtual machines which can be based on Fedora, Debian or even Windows. |
There was a problem hiding this comment.
"based on Fedora, Debian or even Windows" -> "based on popular operating systems such as Fedora, Debian, or even Windows". this makes it more clear that there are other OS templates as well.
|
I haven't been able to reflect on your comments of what would be a stronger approach (rather than just the readability tweaks the pull request contains). Honestly I would suggest looking at what other user-focused OSes have done for introduction:
graphics, screenshots, etc may be valuable. In terms of this draft I think it looks alright, certainly simplified. probably would be good to incorporate links to the glossary for different terms. I think it's an incremental improvement over current version. |
|
Just waiting for any feedback from Marek on this. |
Updated Installation Guide [#5471](QubesOS/qubes-issues#5471)
There was a problem hiding this comment.
I see why this huge wall of text is not exactly a friendly intro. But just removing part of this content, without adding elements making it more interesting (diagrams, screenshots, less dense text structure) doesn't improve the situation that much.
For example diagrams you've listed QubesOS/qubes-issues#5357 were pretty good idea, why you've dropped it here?
Anyway, I agree the part you remove indeed isn't strictly necessary on this page. But it might be better to move it somewhere (FAQ?) instead of completely removing.
I have tried to incorporate your remarks and to make the intro more visually appealing. There is a blend of markdown and HTML. I may need some suggestions on how to make it look ok (although, on the local web server, it looks fine) #871. The diagram attachment needs to be added first. Also, if accepted, parts if not all of the former introduction need to be moved to the FAQ section.
minor typo
|
If we are hoping to merge soon, would you mind resolving the merge conflicts when you have a chance, @luzeal? |
|
@andrewdavidwong I don't mind resolving those conflicts I am just not accustomed on how to do it properly (any kind of help or support will be greatly appreciated). I have pushed a rewritten introduction page yesterday. It needs to be reviewed : see commit 459aa64. @marmarek. Any opinion on this ? |
| </div> | ||
| <div class="col-lg-9 col-md-9"> | ||
| <h3 class="text-center add-bottom">Qubes OS Overview Example</h3> | ||
| <img src="/attachment/site/qubesosdiagram.png" height="600" class="center-block"> |
There was a problem hiding this comment.
This image is missing in qubes-attachment repo.
There was a problem hiding this comment.
Ongoing pull request here
|
Besides one minor technicality, This looks good now, thanks! I don't like the amount of html in markdown document, but also I don't have any better idea to have this nice layout, so it can stay as is. |
Well, the last time I looked at this PR a couple days ago, the "Resolve Conflicts" button was available. That would have allowed you to do it through the GUI, but now the button is grayed out because the changes are "too complex," so I think you'll have to do it through the command line. [Edit: It looks like the button is available again.] You can click on the "use the command line" link for some instructions. Here's a guide for how to resolve conflicts using the command line: https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line |
It is actually my bad. There is a way to edit a file that is being committed to a repository trough the GUI. One other issue is that my pull request does include two files, including an outdated version of the newer installation guide file. I am going to try to remove this extra file from the commit |
I have been unable to remove the outdated file, so I have created another cleaner pull request : #900. Sorry for the duplication. |
What I have tried to do is condense the page and remove information that I believe is a better fit for the FAQ page. If a comparison is still needed ("How does Qubes OS compare to XYZ"), I suggest a table rather than entire sections. The text has been copy-edited. Also, a section on : is "Qubes OS good for me (or a good fit for me)" might be a good idea. Finally, a diagram will eventually be incorporated (discussion on this here).