Port over documentation from third-party sites

[bnvk]

Focusing on the "User Documentation" one of the more jarring things a new user encounters is being redirected to other sites to learn about using Qubes- thus, porting over (and in some cases updating the content dating back to 2011) from the ITL blog, Google Group, and Whonix seem in high order...

The clearest / most important pieces of documentation for porting over are:

• Creating Whonix VMs in Qubes
• Creating NetBSD VM
• Creating Custom NetVMs and ProxyVMs
• How to make proxy for individual tcp connection from networkless VM
• HTTP filtering proxy in Qubes firewall VM
• Booting with GRUB2 and GPT
• Customizing the GUI experience with KDE

Also for inclusion are these posts, which might make sense to move away from "Documentation" and more towards "Intro / Tour" part of the site...

• Further reading: How is Qubes different from…?
• Further reading: Why Qubes is more than a collection of VMs
• Use Qubes without installing: Qubes Live USB (alpha)

Least important, but still worthwhile to port over are the troubleshooting docs

• Installing on system with new AMD GPU (missing firmware problem)
• Solving problems with Macbook Air 2012

[adrelanos]

Whonix HVM? I guess that's a mistake. HVM? Usually I run Whonix in usual PV.

About moving Whonix's documentation to qubes-os.org I answered here:
#1201 (comment)

[adrelanos]

Whonix HVM? I guess that's a mistake. HVM? Usually I run Whonix in usual PV.

About moving Whonix's documentation to qubes-os.org I answered here:
#1201 (comment)

[desci]

I agree with the google groups stuff being adapted and moved to the website, I could help with that

[desci]

I agree with the google groups stuff being adapted and moved to the website, I could help with that

[bnvk]

@desci heya, are you still interested in helping with this? That would be super!

[bnvk]

@desci heya, are you still interested in helping with this? That would be super!

[mfc]

@axon-qubes could you help with this given it's about documentation and you are the master of documentation? this would help tremendously the effort to be able to provide comprehensive offline documentation to users #1019

[mfc]

@axon-qubes could you help with this given it's about documentation and you are the master of documentation? this would help tremendously the effort to be able to provide comprehensive offline documentation to users #1019

[andrewdavidwong]

If there are specific documents that are known and confirmed to be: 1) accurate, 2) up-to-date, and 3) ought to be in the official documentation, then yes, I can help convert those into Markdown and add them to the repo. But it's not clear to me which of the ones in the list above are known to meet all three criteria (and I don't have the expertise to evaluate many of them).

Also, I'm not really that comfortable with taking content from anyone's personal website or blog and appropriating it for the documentation without express permission from the author. Even taking someone's words from a message to the MLs without permission seems a bit wrong.

[andrewdavidwong]

If there are specific documents that are known and confirmed to be: 1) accurate, 2) up-to-date, and 3) ought to be in the official documentation, then yes, I can help convert those into Markdown and add them to the repo. But it's not clear to me which of the ones in the list above are known to meet all three criteria (and I don't have the expertise to evaluate many of them).

Also, I'm not really that comfortable with taking content from anyone's personal website or blog and appropriating it for the documentation without express permission from the author. Even taking someone's words from a message to the MLs without permission seems a bit wrong.

[andrewdavidwong]

I don't think it's a bad thing to have links to external websites, as long as we clearly mark them as external links. We could even have a designated section for them, like "Outside Qubes Guides" or something.

[andrewdavidwong]

I don't think it's a bad thing to have links to external websites, as long as we clearly mark them as external links. We could even have a designated section for them, like "Outside Qubes Guides" or something.

[mfc]

I agree a lot of this does not seem to be relevant, is quite old, doesn't have a clear solution, etc. I've crossed out some of the ones I don't think are relevant, bolded the ones I can understand are.

I think this should initially focus on Qubes materials (like the blogpost re: Qubes Live USB, that should really be in documentation) and on troubleshooting materials.

The greater thrust of this github issue should be to bring in the actual relevant content from Google Group threads that are currently referenced in the existing documentation. For example, this entry: https://www.qubes-os.org/doc/language-localization/

Besides the jarring aspect of having documentation all over the place, this is important for offline documentation so that it actually has the relevant content the user needs.

[mfc]

I agree a lot of this does not seem to be relevant, is quite old, doesn't have a clear solution, etc. I've crossed out some of the ones I don't think are relevant, bolded the ones I can understand are.

I think this should initially focus on Qubes materials (like the blogpost re: Qubes Live USB, that should really be in documentation) and on troubleshooting materials.

The greater thrust of this github issue should be to bring in the actual relevant content from Google Group threads that are currently referenced in the existing documentation. For example, this entry: https://www.qubes-os.org/doc/language-localization/

Besides the jarring aspect of having documentation all over the place, this is important for offline documentation so that it actually has the relevant content the user needs.

[andrewdavidwong]

I've crossed out some of the ones I don't think are relevant.

In the OP? I don't see any crossed-out entries... Now I do. :)

(like the blogpost re: Qubes Live USB, that should really be in documentation)

Added that one in December: https://www.qubes-os.org/doc/live-usb/

For example, this entry: https://www.qubes-os.org/doc/language-localization/

Yeah, not sure who made that page. :\

[andrewdavidwong]

I've crossed out some of the ones I don't think are relevant.

In the OP? I don't see any crossed-out entries... Now I do. :)

(like the blogpost re: Qubes Live USB, that should really be in documentation)

Added that one in December: https://www.qubes-os.org/doc/live-usb/

For example, this entry: https://www.qubes-os.org/doc/language-localization/

Yeah, not sure who made that page. :\

[andrewdavidwong]

I moved the two "further reading" entries as suggested.

[andrewdavidwong]

I moved the two "further reading" entries as suggested.

[mfc]

Added that one in December: https://www.qubes-os.org/doc/live-usb/
I moved the two "further reading" entries as suggested.

nice, check-marked them!

for all the other suggested doc ports, they are really old. I think it would be better to make sure that these Google Group threads are being referenced to in the current Documentation. If not, we should drop them. If so, then maybe get Marek or someone to confirm they are still relevant.

[mfc]

Added that one in December: https://www.qubes-os.org/doc/live-usb/
I moved the two "further reading" entries as suggested.

nice, check-marked them!

for all the other suggested doc ports, they are really old. I think it would be better to make sure that these Google Group threads are being referenced to in the current Documentation. If not, we should drop them. If so, then maybe get Marek or someone to confirm they are still relevant.

[andrewdavidwong]

Language localization is also done.

[andrewdavidwong]

Language localization is also done.

[andrewdavidwong]

I think it would be better to make sure that these Google Group threads are being referenced to in the current Documentation. If not, we should drop them. If so, then maybe get Marek or someone to confirm they are still relevant.

Shouldn't it be the other way around? We should check to see if they're relevant (and accurate) first, then either add or remove them based on that. Old information shouldn't stay in the docs just because it's already there.

[andrewdavidwong]

I think it would be better to make sure that these Google Group threads are being referenced to in the current Documentation. If not, we should drop them. If so, then maybe get Marek or someone to confirm they are still relevant.

Shouldn't it be the other way around? We should check to see if they're relevant (and accurate) first, then either add or remove them based on that. Old information shouldn't stay in the docs just because it's already there.

[mfc]

yep sure, let's loop in @marmarek

[mfc]

yep sure, let's loop in @marmarek

[marmarek]

I haven't reviewed all the linked documentation, but my guess about them:

• Creating NetBSD VM - probably still applies
• Creating Custom NetVMs and ProxyVMs - mostly outdated, but I think also mostly already integrated into our docs
• How to make proxy for individual tcp connection from networkless VM - mostly up to date
• HTTP filtering proxy in Qubes firewall VM - probably up to date

[marmarek]

I haven't reviewed all the linked documentation, but my guess about them:

• Creating NetBSD VM - probably still applies
• Creating Custom NetVMs and ProxyVMs - mostly outdated, but I think also mostly already integrated into our docs
• How to make proxy for individual tcp connection from networkless VM - mostly up to date
• HTTP filtering proxy in Qubes firewall VM - probably up to date

[andrewdavidwong]

Creating NetBSD VM

Done.

Creating Custom NetVMs and ProxyVMs

Skipping. (already integrated)

How to make proxy for individual tcp connection from networkless VM

I don't see an actual guide. Is it the one linked from that message?

HTTP filtering proxy in Qubes firewall VM

Done.

[andrewdavidwong]

Creating NetBSD VM

Done.

Creating Custom NetVMs and ProxyVMs

Skipping. (already integrated)

How to make proxy for individual tcp connection from networkless VM

I don't see an actual guide. Is it the one linked from that message?

HTTP filtering proxy in Qubes firewall VM

Done.

[mfc]

i think this is fine as is and can be closed?

the "guide" for making proxy for individual tcp connection from networkless VM is a bash script from 2012, if it is not already linked in the docs I would lean towards not including it (since "mostly up-to-date" is not "up-to-date").

[mfc]

i think this is fine as is and can be closed?

the "guide" for making proxy for individual tcp connection from networkless VM is a bash script from 2012, if it is not already linked in the docs I would lean towards not including it (since "mostly up-to-date" is not "up-to-date").

[bnvk]

There is still quite a few links in the Docs that point elsewhere. I think these should either be removed (from the Docs) or imported to the repo, full stop.

• Creating Custom NetVMs and ProxyVMs - should be removed from Docs since it's out of date
• How to make proxy for individual tcp connection from networkless VM should probably be the linked one @axon-qubes pointed out should be added

And these three things,

• Booting with GRUB2 and GPT
• Adding SSD storage cache
• Installing on system with new AMD GPU (missing firmware problem)

If we want a page or section on the website of these helpful links that does not get packaged in offline docs, then move these there perhaps...

[bnvk]

There is still quite a few links in the Docs that point elsewhere. I think these should either be removed (from the Docs) or imported to the repo, full stop.

• Creating Custom NetVMs and ProxyVMs - should be removed from Docs since it's out of date
• How to make proxy for individual tcp connection from networkless VM should probably be the linked one @axon-qubes pointed out should be added

And these three things,

• Booting with GRUB2 and GPT
• Adding SSD storage cache
• Installing on system with new AMD GPU (missing firmware problem)

If we want a page or section on the website of these helpful links that does not get packaged in offline docs, then move these there perhaps...

[mfc]

re: "Installing on system with new AMD GPU (missing firmware problem)" from the thread itself the missing package is now included in Qubes. That can be trashed.

re: "Booting with GRUB2..." no solution is actually provided in the thread. That can be trashed.

re: "Adding SSD storage cache", that should be added to the Documentation. Good find.

re: "How to make proxy...", sound good, let's add it.

I agree with you, for everything else we have evaluated they should be removed from Docs. We should lean towards not including topics if we have doubts, as we can always add topics from the google groups if the associated email threads are refreshed by users (acknowledging they are still relevant issues) or similar questions are raised.

[mfc]

re: "Installing on system with new AMD GPU (missing firmware problem)" from the thread itself the missing package is now included in Qubes. That can be trashed.

re: "Booting with GRUB2..." no solution is actually provided in the thread. That can be trashed.

re: "Adding SSD storage cache", that should be added to the Documentation. Good find.

re: "How to make proxy...", sound good, let's add it.

I agree with you, for everything else we have evaluated they should be removed from Docs. We should lean towards not including topics if we have doubts, as we can always add topics from the google groups if the associated email threads are refreshed by users (acknowledging they are still relevant issues) or similar questions are raised.

[andrewdavidwong]

@mfc (#1938):

as a note, I would argue this documentation should be ported to Qubes website so that it can be included in the offline docs (very, very useful information to have offline for users).

• port bridges documentation over to Qubes website

[andrewdavidwong]

@mfc (#1938):

as a note, I would argue this documentation should be ported to Qubes website so that it can be included in the offline docs (very, very useful information to have offline for users).

• port bridges documentation over to Qubes website

[desci]

@bnvk yes. I'll send a pull request whenever I find time to do so.

[desci]

@bnvk yes. I'll send a pull request whenever I find time to do so.

[adrelanos]

@bnvk yes. I'll send a pull request whenever I find time to do so.

Any update?

[adrelanos]

@bnvk yes. I'll send a pull request whenever I find time to do so.

Any update?

[andrewdavidwong]

@mfc: Can we close this issue?

[andrewdavidwong]

@mfc: Can we close this issue?

[desci]

From what I've seen, it has been all done already.

[desci]

From what I've seen, it has been all done already.