search

QubesOS / qubes-issues

The Qubes OS Project issue tracker
https://www.qubes-os.org/doc/issue-tracking/
541 stars 48 forks source link

User doc ToC is badly deisgned #1175

Closed rootkovska closed 9 years ago

rootkovska commented 9 years ago

The main ToC should not be divided into sections named: "Dom0", "DomU", "HVMs", etc, because these are pretty meaningless to most new Qubes users. The doc ToC should be designed much more user-friendly, oriented towards common use-cases.

@bnvk @mfc

mfc commented 9 years ago

linking to user ToC for future reference: https://github.com/QubesOS/qubes-doc/blob/master/UserDoc.md

andrewdavidwong commented 9 years ago

@rootkovska:

The main ToC should not be divided into sections named: "Dom0", "DomU", "HVMs", etc, because these are pretty meaningless to most new Qubes users.

Learning these concepts is part of learning about Qubes, isn't it? If we want users to learn how to safely use Qubes without unintentionally compromising their own security (i.e., shooting themselves in the feet), then we should first teach them these concepts, then explain how to use Qubes while referencing these concepts.

Sure, someone who's brand new to Qubes (and Xen) won't know what they mean. That's why we direct them to read Getting Started and other intro docs first, where we teach them what those terms mean. Once we've laid that foundation, we logically build everything else on top of it.

The doc ToC should be designed much more user-friendly, oriented towards common use-cases.

That sounds more like an FAQ or a quick-start guide. I have nothing against those, but their function is distinct from comprehensive software documentation, which is intended to be a logically-organized reference manual. In other words, "user-friendliness" is always relative to the user. What you describe is friendly to someone who is brand new to Qubes, but it is unfriendly to an experienced Qubes user who knows that she needs specific information about dom0/domU/HVM/etc. but has trouble finding it because the documentation is not organized according to those distinct topics.

In any case, I am not opposed to changing the documentation structure however you like. I just want to share this alternative viewpoint.

marmarek commented 9 years ago

I think Joanna meant that user guide should be organised based on use cases ("how to do thing X") - something that user already know, and from instructions there, user learns what VM types should be used for that. For example if one want to install Windows, the documentation should said that HVM is needed for that - not the opposite (= user needs to know that HVM is needed to find how to install Windows).

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

rootkovska commented 9 years ago

On Sat, Sep 19, 2015 at 02:10:52AM -0700, Marek Marczykowski-Górecki wrote:

I think Joanna meant that user guide should be organised based on use cases ("how to do thing X") - something that user already know, and from instructions there, user learns what VM types should be used for that. For example if one want to install Windows, the documentation should said that HVM is needed for that - not the opposite (= user needs to know that HVM is needed to find how to install Windows).

Exactly.

andrewdavidwong commented 9 years ago

Yes, I understood exactly what you meant. I was just offering an alternative viewpoint. :)

Ok, so, let's say we have a page called "How to install Windows in Qubes." Would this page be under some more general topic? Perhaps it would be grouped together with other pages like, "How to install Debian in Qubes," and the general topic heading would be something like, "How to use other OSes in Qubes"?

Is this what you have in mind? If so, do you have a list of such general topics in mind, or should we crowd-source it?

rootkovska commented 9 years ago

On Sat, Sep 19, 2015 at 05:26:10AM -0700, Axon wrote:

Ok, so, let's say we have a page called "How to install Windows in Qubes." Would this page be under some more general topic? Perhaps it would be grouped together with other pages like, "How to install Debian in Qubes," and the general topic heading would be something like, "How to use other OSes in Qubes"?

Yes.

Is this what you have in mind? If so, do you have a list of such general topics in mind, or should we crowd-source it?

Generally, I think we should also keep the ToC structure as flat as possible, avoiding too much nesting. I think 2-level (as used e.g. on help.github.com) should be just enough. I've noticed "The Normal People" have problems navigating too-deep table of contents, and generally perceive them as too unfriendly, complex.

So, just to try some idea, how about something like that:

  1. Basics
    • Fundamental concepts (security by compartmentalization)
    • How does Qubes OS compare to ...?
    • Getting started guide
  2. Choosing proper hardware for Qubes OS
    • Fast lane: pick one of the "Qubes Certified" laptops
    • More discussion about hardware requirements
    • The community-maintained Hardware Compatibility List

  3. Installation guides

    • Fast lane: try Qubes Live USB
    • Getting and verifying Qubes installation media
    • Planning your installation
    • Qubes Live edition
    • Installing additional templates: Linux (Debian, Whonix)
    • Installing additional OSes
    • Installing Windows templates

    ...

  4. Customization guides
    • Customizing the GUI domain
    • Customizing the default (Fedora) template
    • Using alternative Window Managers in GUI domain: Xfce4
    • Using alternative Window Managers in GUI domain: XYZ ...
  5. Typical workflows
    • Copying files between VMs (yes, even though this might be explained in Getting Started, it should be repeated here, possibly with link to GSG)
    • Copying clipboard between VMs
    • Using Disposable VMs
    • Opening files in other VMs (qvm-open-in-vm)
    • Updating Qubes and templates
    • Making backups ...
    • Command line reference
  6. Maintenance and administration (potentially should be divided into more sections?)
    • Understanding Qubes qrexec services and policy
    • Qubes networking at a glimpse
    • Understanding Qubes firewall and leak prevention
    • Advanced networking topologies
    • VPN ProxyVMs
    • Understanding Qubes templates mechanism
    • Finding logs, reporting problems
    • Writing exemplary qrexec service ...
    • Developer documentation (linking to our dev docs, yes, we should repeat it here, even though it might be linked from the top website)
  7. Special use-cases
    • Qubes Whonix integration
    • Qubes Split GPG
    • Qubes TorVM

BTW, we should not assume people reading this are idiots, most people who will come to Qubes are probably gonna be reasonably smart. But we should assume these people are busy with their own stuff, and will not read all the materials from the start page to the last page. They will come to the docs to solve the problems they face in between the work they do. Everything should be self-explanatory as much as possible. It's a mistake to think: "now we don't need to explain that, or we can use this XYZ acronym that only 1 people on the planet understand, because it got explained on page 1203 in the document #42". No.

joanna.

andrewdavidwong commented 9 years ago

So, just to try some idea, how about something like that: [...]

Thank you! Looks like a great starting point.

It's a mistake to think: "now we don't need to explain that, or we can use this XYZ acronym that only 1 people on the planet understand, because it got explained on page 1203 in the document #42".

LOL

I must admit I sometimes find it tempting to think this way, but yes, ultimately I agree.

andrewdavidwong commented 9 years ago

Restructuring implemented. Does it still need work, or should we close this ticket?

rootkovska commented 9 years ago

Thanks, Axon!

rootkovska commented 9 years ago

Ok, one more thing -- it seems to me that we don't really need an extra level of indirection in the form of this page: https://www.qubes-os.org/doc/

Especially, all the things listed under the section "For Users" should really land under what we currently have at /doc/UserDoc/, otherwise the question arises what is the criterium for putting them into /doc/ under "For Users" vs. /doc/UserDoc/.

Similarly, I think we should move everything listed under "For Developers" to: https://www.qubes-os.org/doc/SystemDoc/

Then the question is do we still want to leave this /doc/ page, or rather, have the top-level menu link directly to /doc/UserDoc/, and a separate menu entry ("Development"?) link to doc/SystemDoc/ (plus also link there from the bottom of /doc/UserDoc/ as it could also be seen as containing further documentation resources, sometime of interest to power users). The /doc/ should then redirect to /doc/UserDoc/ for compatibility.

andrewdavidwong commented 9 years ago

I agree. Really, the whole structure of the site needs to be revamped, because right now it doesn't really make sense. For example, the download, screenshot, and contact pages are all nested under /doc/, which is an artifact of the old TracWiki system. I'll work on this right now.

Edit: Done.

mfc commented 9 years ago

Agreed on the need for a site structure revamp, looping in @bnvk as well.

One thing I've noticed is that the News on the front page is getting quite long, might be worth pushing older news to a separate News / In the News page (or having all the news there, and just the 2-3 most recent on the front page).

andrewdavidwong commented 9 years ago

@mfc: I was thinking the same thing about the News section. It's kind of funny that "Recent News" includes entries dating back to early 2013.

Edit: Removed old entries here. @rootkovska, feel free to revert that commit if you want to keep those entries.

bnvk commented 9 years ago

...it seems to me that we don't really need an extra level of indirection in the form of this page: https://www.qubes-os.org/doc/

Yes, that is a great idea and significant improvement! I just opened issue #1200 as I think the docs being refactored as well as where things like "Fast lane: try Qubes Live USB" fit into the greater scheme should be considered at a very high level!

Similarly, I think we should move everything listed under "For Developers" to:

I think having a separate documentation for developers specifically makes tremendous sense :+1:

News on the front page is getting quite long, might be worth pushing older news to a separate News

I agree and shall take this into account in my re-design!

andrewdavidwong commented 9 years ago

@bnvk, I've just revamped the site significantly. Take a look at the new structure. I think it addresses many of these issues.

mfc commented 9 years ago

@axon-qubes thanks for the revamp, it's looking so much better!

Where is the new location for the UserDoc on git to edit? It seems to have moved from https://github.com/QubesOS/qubes-doc/blob/master/UserDoc.md.

One thing I noticed is there isn't a listing for Whonix template under Managing Operating System with Qubes. Something like:

Templates: Whonix

Instead there is "Creating Whonix HVMs in Qubes" further down with a link directly to the Whonix page, which I think should be removed.

andrewdavidwong commented 9 years ago

@axon-qubes thanks for the revamp, it's looking so much better!

Thanks!

Where is the new location for the UserDoc on git to edit? It seems to have moved from https://github.com/QubesOS/qubes-doc/blob/master/UserDoc.md.

The source file is here now: https://github.com/QubesOS/qubesos.github.io/blob/master/pages/doc.md (But it might need to be moved back into qubes-doc. We'll see.)

And on the website, it's here: https://www.qubes-os.org/doc/

One thing I noticed is there isn't a listing for Whonix template under Managing Operating System with Qubes. Something like:

Templates: Whonix

Instead there is "Creating Whonix HVMs in Qubes" further down with a link directly to the Whonix page, which I think should be removed.

Done.

mfc commented 9 years ago

awesome, thanks on both counts!

marmarek commented 9 years ago

On Wed, Sep 23, 2015 at 04:43:34AM -0700, Axon wrote:

The source file is here now: https://github.com/QubesOS/qubesos.github.io/blob/master/pages/doc.md (But it might need to be moved back to into qubes-doc. We'll see.)

Yes, most likely - for offline docs.

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

andrewdavidwong commented 9 years ago

(But it might need to be moved back to into qubes-doc. We'll see.)

Yes, most likely - for offline docs.

Ok. Initially, my reasoning was that these pages are part of the website, not the documentation. However, I now see that it makes sense to include at least some of them in qubes-doc, given that we're also going to merge qubes-attachment into qubes-doc so that qubes-doc eventually becomes a standalone thing.

So, which of those pages should go (back) into qubes-doc?

marmarek commented 9 years ago

On Wed, Sep 23, 2015 at 04:57:15AM -0700, Axon wrote:

So, which of those pages should go (back) into qubes-doc?

I think doc and intro.

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

andrewdavidwong commented 9 years ago

I think doc and intro.

If qubes-attachment is going to be merged into qubes-doc, then it might make sense to include screenshots.md as well, since several images in qubes-attachment are probably linked only there (and not on any other page). (Are we worried about "bloat"?)

marmarek commented 9 years ago

On Wed, Sep 23, 2015 at 05:35:41AM -0700, Axon wrote:

I think doc and intro.

If qubes-attachment is going to be merged into qubes-doc, then it might make sense to include screenshots.md as well, since several images in qubes-attachment are probably linked only there (and not on any other page). (Are we worried about "bloat"?)

I was thinking about it and actually IMO we can leave qubes-attachment as a separate repo.

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

andrewdavidwong commented 9 years ago

I was thinking about it and actually IMO we can leave qubes-attachment as a separate repo.

Ok. Just pull the necessary images when creating the offline HTML/PDF?

andrewdavidwong commented 9 years ago

doc.md and intro.md moved back into qubes-doc

marmarek commented 9 years ago

On Wed, Sep 23, 2015 at 05:37:40AM -0700, Axon wrote:

I was thinking about it and actually IMO we can leave qubes-attachment as a separate repo.

Ok. Just pull the necessary images when creating the offline HTML/PDF?

I think for offline doc we'll have another repo similar to qubesos.github.io, which will pull the qubes-doc and qubes-attachment. And place them on appropriate layout, without nav bar etc (almost empty in practice).

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

mfc commented 9 years ago

hey @axon-qubes I think with the clean-up moving stuff, redirects might be needed.

I just ran into this link marek created a day ago that is dead now: https://github.com/QubesOS/qubes-issues/issues/1206#issuecomment-142443022

There may be a bunch of links out there on the internet to Qubes documentation pages that are now dead.

marmarek commented 9 years ago

Yes, each rename must be followed by appropriate redirect_from: header. All internal links must be updated to the new location anyway. @axon-qubes do you need some help with automating this task?

andrewdavidwong commented 9 years ago

@mfc:

hey @axon-qubes I think with the clean-up moving stuff, redirects might be needed.

I just ran into this link marek created a day ago that is dead now:

1206 (comment)

There may be a bunch of links out there on the internet to Qubes documentation pages that are now dead.

@marmarek:

Yes, each rename must be followed by appropriate redirect_from: header. All internal links must be updated to the new location anyway. @axon-qubes do you need some help with automating this task?

Don't worry, it was just a trivial mistake: I accidentally put an underscore (_) at the beginning of the _unsorted directory, which caused it to be ignored by Jekyll. I've now removed that underscore, so all the pages in that directory work now.

So, it actually wasn't a problem with redirects at all. The redirects are working fine.

andrewdavidwong commented 9 years ago

All internal links must be updated to the new location anyway.

@marmarek, what do you mean by this?

marmarek commented 9 years ago

On Thu, Sep 24, 2015 at 02:43:51AM -0700, Axon wrote:

All internal links must be updated to the new location anyway.

@marmarek, what do you mean by this?

Links between pages should use canonical name of the page, otherwise redirect will happen. And apparently redirects generated by jekyll use absolute URL, with http instead of https... And even if we fix that, its better to avoid unnecessary redirect.

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

andrewdavidwong commented 9 years ago

Links between pages should use canonical name of the page, otherwise redirect will happen. And apparently redirects generated by jekyll use absolute URL, with http instead of https... And even if we fix that, its better to avoid unnecessary redirect.

Yes, agreed.

(I think it would still be a good idea to enabled "force all HTTPS" in Cloudflare just in case we miss any, and for old links from MLs and other websites which get redirected. I know it's still problematic because the connection is unencrypted at first, but it'll at least look better to users who check the URL after being redirected.)

marmarek commented 9 years ago

On Thu, Sep 24, 2015 at 11:19:37AM -0700, Axon wrote:

(I think it would still be a good idea to enabled "force all HTTPS" in Cloudflare just in case we miss any, and for old links from MLs and other websites which get redirected. I know it's still problematic because the connection is unencrypted at first, but it'll at least look better to users who check the URL after being redirected.)

Done. @woju, can we have a script for finding https->http redirects? Similar to the one for dead links.

Best Regards, Marek Marczykowski-Górecki Invisible Things Lab A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing?

woju commented 9 years ago

On Thu, Sep 24, 2015 at 01:14:56PM -0700, Marek Marczykowski-Górecki wrote:

Done. @woju, can we have a script for finding https->http redirects? Similar to the one for dead links.

Yesterday, as part of the CamelCase rewrite, I pushed script which rewrites all relative links with their canonical versions (permalink:). Should be sufficient.

marmarek commented 9 years ago

Is it all done? Or something left to do in this ticket?

andrewdavidwong commented 9 years ago

Is it all done? Or something left to do in this ticket?

The original ticket task is done.

A couple other matters have been discussed in the comments. I recommend closing as complete, then people can create new tickets based on comments in this thread if they feel the need.