User doc ToC is badly deisgned

[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. The doc ToC should be designed much more user-friendly, oriented towards common use-cases.

@bnvk @mfc

[mfc]

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

[mfc]

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

[andrewdavidwong]

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

[andrewdavidwong]

@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]

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?

[marmarek]

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]

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.

[rootkovska]

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]

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?

[andrewdavidwong]

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]

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.

[rootkovska]

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]

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]

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]

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

[andrewdavidwong]

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

[rootkovska]

Thanks, Axon!

[rootkovska]

Thanks, Axon!

[rootkovska]

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.

[rootkovska]

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]

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.

[andrewdavidwong]

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]

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

[mfc]

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]

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

[andrewdavidwong]

@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]

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

[bnvk]

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

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

[andrewdavidwong]

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

[mfc]

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

[mfc]

@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]

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

[andrewdavidwong]

@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]

awesome, thanks on both counts!

[mfc]

awesome, thanks on both counts!

[marmarek]

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?

[marmarek]

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]

(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?

[andrewdavidwong]

(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]

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?

[marmarek]

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]

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"?)

[andrewdavidwong]

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]

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?

[marmarek]

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]

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]

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]

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

[andrewdavidwong]

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

[marmarek]

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?

[marmarek]

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]

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.

[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?

[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?

[andrewdavidwong]

@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]

@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]

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

@marmarek, what do you mean by this?

[andrewdavidwong]

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

@marmarek, what do you mean by this?

[marmarek]

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?

[marmarek]

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]

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

[andrewdavidwong]

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]

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?

[marmarek]

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]

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.

[woju]

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]

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

[marmarek]

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

[andrewdavidwong]

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.

[andrewdavidwong]

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.