User doc ToC is badly deisgned #1175

rootkovska · 2015-09-07T07:54:14Z

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 · 2015-09-12T16:14:14Z

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

andrewdavidwong · 2015-09-19T05:33:52Z

@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 · 2015-09-19T09:10:51Z

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 · 2015-09-19T10:18:15Z

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 · 2015-09-19T12:26:07Z

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 · 2015-09-19T13:31:28Z

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:

Basics
- Fundamental concepts (security by compartmentalization)
- How does Qubes OS compare to ...?
- Getting started guide
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
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
...
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
  ...
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
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)
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 · 2015-09-19T13:44:40Z

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.

_doc: tag axon_a8db6eb5 tagger Axon <[email protected]> 1442783348 +0000 Tag for commit a8db6eb5fa1b50c6371714ea4a798ec84c7e0707 gpg: Signature made Sun 20 Sep 2015 11:09:08 PM CEST using RSA key ID 2A019A17 gpg: Good signature from "Axon (Qubes Documentation Signing Key)" a8db6eb Clarify oathtool procedure 41fea2b Add Multi-factorAuthentication to ToC 40f312f Minor wording changes b19f2c7 Create Multi-factor Authentication page 2540091 Restructure UserDoc table of contents (QubesOS/qubes-issues#1175) attachment: tag axon_9c38eec8 tagger Axon <[email protected]> 1442780093 +0000 Tag for commit 9c38eec gpg: Signature made Sun 20 Sep 2015 10:14:53 PM CEST using RSA key ID 2A019A17 gpg: Good signature from "Axon (Qubes Documentation Signing Key)" 9c38eec Add multi-factor authentication example screenshots 9b3cdee VersionScheme: release-cycle.svg

andrewdavidwong · 2015-09-21T13:58:16Z

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

rootkovska · 2015-09-21T16:38:20Z

Thanks, Axon!

rootkovska · 2015-09-21T22:32:12Z

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 · 2015-09-22T06:52:02Z

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 · 2015-09-22T09:31:23Z

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 · 2015-09-22T10:02:26Z

@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 · 2015-09-22T18:27:16Z

...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 👍

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 · 2015-09-22T18:31:29Z

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

mfc · 2015-09-23T09:45:13Z

@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 · 2015-09-23T11:43:32Z

@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 · 2015-09-23T11:51:13Z

awesome, thanks on both counts!

marmarek · 2015-09-23T11:52:08Z

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 · 2015-09-23T11:57:14Z

(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 · 2015-09-23T12:10:53Z

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 · 2015-09-23T12:35:40Z

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 · 2015-09-23T12:36:44Z

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 · 2015-09-23T12:37:38Z

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 · 2015-09-23T12:45:11Z

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

marmarek · 2015-09-23T12:58:27Z

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 · 2015-09-23T21:51:35Z

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 · 2015-09-23T23:25:07Z

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 · 2015-09-24T08:56:10Z

@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 · 2015-09-24T09:43:50Z

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

@marmarek, what do you mean by this?

marmarek · 2015-09-24T12:48:55Z

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 · 2015-09-24T18:19:36Z

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 · 2015-09-24T20:14:37Z

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 · 2015-09-25T10:07:04Z

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 · 2015-10-05T15:11:18Z

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

andrewdavidwong · 2015-10-06T22:42:37Z

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.

rootkovska added enhancement C: doc P: major Priority: major. Between "default" and "critical" in severity. labels Sep 7, 2015

rootkovska added this to the Release 3.1 milestone Sep 7, 2015

andrewdavidwong pushed a commit to QubesOS/qubes-doc that referenced this issue Sep 20, 2015

Restructure UserDoc table of contents (QubesOS/qubes-issues#1175)

2540091

rootkovska closed this as completed Sep 21, 2015

rootkovska reopened this Sep 21, 2015

bnvk mentioned this issue Sep 22, 2015

Create new information architecture for website #1200

Closed

marmarek closed this as completed Oct 6, 2015

iuriguilherme mentioned this issue Oct 13, 2015

Linux PV / HVM documentation #1332

Open

adrelanos mentioned this issue Feb 24, 2016

change default proxy-vm: sys-whonix -> system-tor #1777

Closed

User doc ToC is badly deisgned #1175

User doc ToC is badly deisgned #1175

Comments

rootkovska commented Sep 7, 2015

mfc commented Sep 12, 2015

andrewdavidwong commented Sep 19, 2015

marmarek commented Sep 19, 2015

rootkovska commented Sep 19, 2015

andrewdavidwong commented Sep 19, 2015

rootkovska commented Sep 19, 2015

andrewdavidwong commented Sep 19, 2015

andrewdavidwong commented Sep 21, 2015

rootkovska commented Sep 21, 2015

rootkovska commented Sep 21, 2015

andrewdavidwong commented Sep 22, 2015

mfc commented Sep 22, 2015

andrewdavidwong commented Sep 22, 2015

bnvk commented Sep 22, 2015

andrewdavidwong commented Sep 22, 2015

mfc commented Sep 23, 2015

andrewdavidwong commented Sep 23, 2015

mfc commented Sep 23, 2015

marmarek commented Sep 23, 2015

andrewdavidwong commented Sep 23, 2015

marmarek commented Sep 23, 2015

andrewdavidwong commented Sep 23, 2015

marmarek commented Sep 23, 2015

andrewdavidwong commented Sep 23, 2015

andrewdavidwong commented Sep 23, 2015

marmarek commented Sep 23, 2015

mfc commented Sep 23, 2015

marmarek commented Sep 23, 2015

andrewdavidwong commented Sep 24, 2015

andrewdavidwong commented Sep 24, 2015

marmarek commented Sep 24, 2015

andrewdavidwong commented Sep 24, 2015

marmarek commented Sep 24, 2015

woju commented Sep 25, 2015

marmarek commented Oct 5, 2015

andrewdavidwong commented Oct 6, 2015