Re: [qubes-users] Re: Qubes 4.0 Documentation
-BEGIN PGP SIGNED MESSAGE- Hash: SHA256 On Fri, Jan 26, 2018 at 11:37:31PM -0600, Andrew David Wong wrote: > On 2018-01-26 05:14, awokd wrote: > > On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote: > >> On 2018-01-25 12:28, awokd wrote: > >>> 1. Should I open an issue for tracking and move the discussion > >>> over there? Move to qubes-devel? Keep here? > >> > >> Please open an issue in qubes-issues. > > > > https://github.com/QubesOS/qubes-issues/issues/3495 > > > > > >> I agree that the tool man pages should not be shared between 3.2 > >> and 4.0 (but they probably wouldn't be anyway, due to the nature > >> of the system just described). > > > > What will be the naming convention for direct links? I can see > > sometimes we'd want to link to the latest version of qvm-whatever, > > and other times when we want to link to a specific major version. > > > > We could either have different subdirectories for each version or > include the version in the page name, as we do for some other > version-specific pages. I'd go with different subdirectories - it will be easier to handle (both generate and later reference). - -- 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? -BEGIN PGP SIGNATURE- iQEzBAEBCAAdFiEEhrpukzGPukRmQqkK24/THMrX1ywFAlps18QACgkQ24/THMrX 1yyZ8Af+P6P0CjFiUiW1HdMHe5NCje/ZxjJxpSE+HXLPT/2Hr+Bhm/CjIGXS7cOr /IO920qG3+c6EmDxBplIDCCaov5xz3jxWih5JjtRR9FUx29yCGwm9Fu2vHPiiaDJ RvEmTFRfkGgsm3EOJ1U/j7uao7uuMPrpRmyVNyWWIKHKPk6S/DmBodVQepl7uE2Q Mw/uXITtl3EaBfGoN/W6lnCNc0/0E6wPLUv6rsMaeSEAcihzRlrzAXDDdcNYWMQL EWEYV/mqdXjtksqtzLMCpQwiCkuGBOhIptQjRZ3DqBPQZQm5eQH4+tbytBR63nby tQqOXmUDWjBFdj3UuulZkQVbRUxNuw== =6lu1 -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups "qubes-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-users+unsubscr...@googlegroups.com. To post to this group, send email to qubes-users@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-users/20180127194924.GF2653%40mail-itl. For more options, visit https://groups.google.com/d/optout.
Re: [qubes-users] Re: Qubes 4.0 Documentation
-BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 2018-01-26 05:14, awokd wrote: > On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote: >> On 2018-01-25 12:28, awokd wrote: >>> 1. Should I open an issue for tracking and move the discussion >>> over there? Move to qubes-devel? Keep here? >> >> Please open an issue in qubes-issues. > > https://github.com/QubesOS/qubes-issues/issues/3495 > > >> I agree that the tool man pages should not be shared between 3.2 >> and 4.0 (but they probably wouldn't be anyway, due to the nature >> of the system just described). > > What will be the naming convention for direct links? I can see > sometimes we'd want to link to the latest version of qvm-whatever, > and other times when we want to link to a specific major version. > We could either have different subdirectories for each version or include the version in the page name, as we do for some other version-specific pages. >> I think it makes sense to handle these cases specifically, by >> creating a page that collects all the versions of each one. I'll >> do this now. > > Thank you. > >> In general, it's worth thinking about whether we even want to >> keep severely outdated category 2 documentation around. Does it >> have any value anymore, or will it just produce misleading search >> results? (Note that it will all remain permanently archived in >> the git revision history, so it's mainly a question of visibility >> on the website.) > > My vote is to axe it. > - -- Andrew David Wong (Axon) Community Manager, Qubes OS https://www.qubes-os.org -BEGIN PGP SIGNATURE- iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpsEAwACgkQ203TvDlQ MDAhCg//Xxt+qfhlLYXYoudWzpGX9WSwwBQHZpH/A6j0zZEhgIYl/sPtF66Mmxwx QOWA7DEElbojIRQ+DmVvt8FB4RWJkxRw9mqUY8aMbh5qVXHMbjiBDLfWDsnwjRnJ ZJREO450qYHDesg/g+8DasFbXE7D1qBxuUBM+uRvTaqzj9fhUUtCvI0NAUBZcv/u 6+0IFSTbm6fw4XyhfVYJEXpjuBI2WCfA++6mFlnAx0UY6AQenlnxRtOgEdK+N8wb 403fX7e0CaJhzCnXd+4g5i9Dm2ogewNAwHK/TLPXathJzmYmruZgzIJgiSrcUwVB vHrsPi3ZqPgR6vZkW/DwMBBjz0s+Y/WudBpDhFeXDJ/JbOU5mW1E/63LpCyB8p0+ V9Y+4pAkbdWuzX8JojNGSJ6K0ZrsGRgb3QIyhi8yRCwgNqUqjW6y/VitmeAi3HGT KPSaM8b8MjnEtfI6KQUNPOqS8lO9cX5D5tsPu64FGXx7ZTieVdCOl8oDjWduc4hU 1W2FxzH1p+hr6X17qYsUbwbyyr2lqV1so8g5ASitOflcMNqPHN4rfXRI9dKu5gfL 8PmpDk2hQUeaLy1RbpBrUzbHp1JnqmwMg1bfm9BJrqDbyOqXJapVLAuoAvg/bQmZ QfzRQPrZpjpS/6VW+qTojRj0zGadqE7NBiBvBIQF+0Z5bZ/Bck8= =U+U5 -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups "qubes-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-users+unsubscr...@googlegroups.com. To post to this group, send email to qubes-users@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-users/eb46324a-c834-3b0c-24e6-22a4fdeb1191%40qubes-os.org. For more options, visit https://groups.google.com/d/optout.
Re: [qubes-users] Re: Qubes 4.0 Documentation
-BEGIN PGP SIGNED MESSAGE- Hash: SHA512 On 2018-01-26 05:38, 'awokd' via qubes-users wrote: > On Fri, January 26, 2018 9:22 am, Alex Dubois wrote: >> On Friday, 26 January 2018 03:36:33 UTC, Andrew David Wong >> wrote: > >> Happy to contribute. maybe we can have a direct conversation so >> that we can discuss what is needed and where I feel >> comfortable... > > Speaking only on my own behalf of course, thank you. Editing the > docs is pretty straight-forward > (https://www.qubes-os.org/doc/doc-guidelines/), so I'd suggest > jumping in and editing whatever you are comfortable with. I'm > coming across documents where someone else has already gone in and > called out or updated with R4.0 content, so thanks to those > contributors as well! > I agree. - -- Andrew David Wong (Axon) Community Manager, Qubes OS https://www.qubes-os.org -BEGIN PGP SIGNATURE- iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpr1q4ACgkQ203TvDlQ MDAmmw//f5oa73EABlkL+6g78pOalsHZaX9jYbcwvfpZAycrdpYaxiXxxeIAjY/+ p5PZQe/0b5CQf1N3g7jcDcN7HzqztZgtpMmOPyWrZ1VMMBfJ2d8TmjAC9OU/d0Pv Jf7KujBhD+hJVRh2Zel8xIis89+5tdM2IKWJsetAuZgTssmvGVAXy+NzEXzchBbh jszjL5RixsxhSeBVkvNCuBSiD3XGGYBp3beOj8zvvnLu5mTVJA7p2hI3MAtADqlU yiWIpoTz1FBLfbo33ETl9O9NTP9v9pzs3175Llprf93XWABV9qZEY+QoAPZdEAac C/T0Fm9UZFJ/2xaNQiNBHqzO7CSOVUqOpwJQoiQBleeorIvCSpfeJdCEqUQ7PGKS rnAq9Sm8Fr7BiDfXQU99MJQbqmMeJVtq6BeUUx/JlcS7gW7KUzZ3W9LfirMdHRdQ KAuaG/pqio1LBtZatbXBUvCnQ8uWctaPJ4YknqPc99rvgCFl3if3dFxQRBcr56RH nXcPUifk+jbgFQzEjiyCzANYS9OdmXBsYa0QPWN/ZdIw4Dvl23J6qqcY5Vs7pEyJ EEm/sLiinPrQo9h5WjH7+55PQRcnPqm71rwC8fMlblde2Nx89fMgbksB0BQIyX+x pTxjh2feeWpDtf/bL1zfJ+zNAR2mEyxJML0Dbc6+Kj+EBTwGUtU= =czGG -END PGP SIGNATURE- -- You received this message because you are subscribed to the Google Groups "qubes-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-users+unsubscr...@googlegroups.com. To post to this group, send email to qubes-users@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-users/bc6054e7-98f3-b388-6bcc-f45109cc60b2%40qubes-os.org. For more options, visit https://groups.google.com/d/optout.
Re: [qubes-users] Re: Qubes 4.0 Documentation
On Fri, January 26, 2018 9:22 am, Alex Dubois wrote: > On Friday, 26 January 2018 03:36:33 UTC, Andrew David Wong wrote: > Happy to contribute. maybe we can have a direct conversation so that we > can discuss what is needed and where I feel comfortable... Speaking only on my own behalf of course, thank you. Editing the docs is pretty straight-forward (https://www.qubes-os.org/doc/doc-guidelines/), so I'd suggest jumping in and editing whatever you are comfortable with. I'm coming across documents where someone else has already gone in and called out or updated with R4.0 content, so thanks to those contributors as well! -- You received this message because you are subscribed to the Google Groups "qubes-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-users+unsubscr...@googlegroups.com. To post to this group, send email to qubes-users@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-users/012f06ff57be8fd2c1405d791ae01424.squirrel%40tt3j2x4k5ycaa5zt.onion. For more options, visit https://groups.google.com/d/optout.
Re: [qubes-users] Re: Qubes 4.0 Documentation
On Fri, January 26, 2018 3:36 am, Andrew David Wong wrote: > On 2018-01-25 12:28, awokd wrote: >> 1. Should I open an issue for tracking and move the discussion >> over there? Move to qubes-devel? Keep here? > > Please open an issue in qubes-issues. https://github.com/QubesOS/qubes-issues/issues/3495 > I agree that the tool man pages should not be shared between 3.2 and > 4.0 (but they probably wouldn't be anyway, due to the nature of the > system just described). What will be the naming convention for direct links? I can see sometimes we'd want to link to the latest version of qvm-whatever, and other times when we want to link to a specific major version. > I > think it makes sense to handle these cases specifically, by creating a > page that collects all the versions of each one. I'll do this now. Thank you. > In general, it's worth thinking about whether we even want to keep > severely outdated category 2 documentation around. Does it have any value > anymore, or will it just produce misleading search results? (Note that it > will all remain permanently archived in the git revision history, so it's > mainly a question of visibility on the website.) My vote is to axe it. -- You received this message because you are subscribed to the Google Groups "qubes-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to qubes-users+unsubscr...@googlegroups.com. To post to this group, send email to qubes-users@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/qubes-users/835aa4381a02b34be8f3162224d965f0.squirrel%40tt3j2x4k5ycaa5zt.onion. For more options, visit https://groups.google.com/d/optout.
[qubes-users] Re: Qubes 4.0 Documentation
On Friday, 26 January 2018 03:36:33 UTC, Andrew David Wong wrote:
> -BEGIN PGP SIGNED MESSAGE-
> Hash: SHA512
>
> On 2018-01-25 12:28, awokd wrote:
> > Resuming working my way through splitting up the documentation now
> > that the 3.2 vs. 3.3 question has been mostly settled. Some
> > general questions:
> >
> > 1. Should I open an issue for tracking and move the discussion
> > over there? Move to qubes-devel? Keep here?
>
> Please open an issue in qubes-issues.
>
> (Doing so does not preclude discussion here or on qubes-devel.)
>
> > 2. The command line tools in particular
> > (https://www.qubes-os.org/doc/vm-tools/ and
> > https://www.qubes-os.org/doc/dom0-tools/) seem Wrong to try to
> > share the same pages for 3.2 and 4.0. Not only is the selection of
> > commands slightly different between versions, but many have
> > slightly different options ("-a" vs. "a"). I'm thinking of copying
> > all the existing pages, appending "4" so they can be linked to
> > directly, and putting in their own section. Thoughts?
>
> Those pages are automatically generated from the man pages stored with
> the tools' source code in their own respective repos, so any changes
> to those pages in qubes-doc will be overwritten. Changes should be
> made to the original files instead. That way, the changes will persist
> when the qubes-doc versions are automatically generated.
>
> I agree that the tool man pages should not be shared between 3.2 and
> 4.0 (but they probably wouldn't be anyway, due to the nature of the
> system just described).
>
> > 3. Some of these documents are pretty outdated. Should we have an
> > Archive link and move stuff like
> > https://www.qubes-os.org/doc/template/fedora/upgrade-18-to-20/ to
> > it so it doesn't clutter up the main Docs page?
> >
> There are two categories of outdated documents:
>
> 1. Documents that we want updated (but that no one has updated yet).
> 2. Documents that are about old topics (but are otherwise good).
>
> I don't think it would make sense to move documents of category 1 into
> an archive section, since that would incorrectly suggest that we don't
> want or expect them to be updated.
>
> The old Fedora upgrade documents fall into category 2. However, it
> looks like they (and perhaps the release notes for unsupported Qubes
> versions) are the only major offenders visible in the main table of
> contents. This is understandable, since a new version of the document
> gets added each time there's a new version of the corresponding
> software. I think it makes sense to handle these cases specifically,
> by creating a page that collects all the versions of each one. I'll do
> this now.
>
> In general, it's worth thinking about whether we even want to keep
> severely outdated category 2 documentation around. Does it have any
> value anymore, or will it just produce misleading search results?
> (Note that it will all remain permanently archived in the git revision
> history, so it's mainly a question of visibility on the website.)
>
> - --
> Andrew David Wong (Axon)
> Community Manager, Qubes OS
> https://www.qubes-os.org
>
> -BEGIN PGP SIGNATURE-
>
> iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpqojUACgkQ203TvDlQ
> MDDG4Q//Q6ND5fzToFv6KKQn4SzkcUSIIZQKtMPTlG9BkC7UCgjFZ+7sxrLA1N5X
> H+9Z88+QNRL6FBOa6DHpFZOOA6vomzw0HXkTF+g9VcplsJIFZh6iB7lpSta1XwKU
> 1DG+ayF0oDd8PxKtSjaslMWRsr9p9cApPM7G+z6sGLB34LLZfolx19FRhwcpfBBK
> 09wyaAzmr5sF9oO8rSxC1llz5u75GatXUu+tHIc3Jh9C4hBtX7MSwyoq7eTkXnKQ
> VpS35O8thmhm6cEuyNQsUD7ia853lWRcdTur1Am7GIx3jwl7VBQ6YCqanLRLueaI
> tm4LbBfNrZcxFexHp0mB+veDeIfkC4cJZm8/sbjrHEicK6Cuvp5E0E6iLOaMw9gI
> y3D1ypbEwMXyYQFPWW0h488pNow9RCrTHTcvBhgyIBw0xhCe0j89RZpbV3UB79k1
> n5YRoj36XXRmHho/KVIlFMrzsXE6q9sawU8P1/Q7mBjX3fQLDoOEwFMtHRZTiFLk
> NOkqv328xsqJy1smKgfFI4cpNMa1+Be0zGjqRWjBFNTqWEoNPkAbDbhbiwYPZYop
> CW0lDS6b6dc2KCMcxlP+3BwuFC+pS9Yw/Qw2B0yceVjrH0YnLoVkOaqC6ojGx6DH
> JAFtJLB6FbXssbK3JASOvGKpMxcktfQe3quJZmTaMY2yLkBaomA=
> =8MfO
> -END PGP SIGNATURE-
Happy to contribute. maybe we can have a direct conversation so that we can
discuss what is needed and where I feel comfortable...
--
You received this message because you are subscribed to the Google Groups
"qubes-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to qubes-users+unsubscr...@googlegroups.com.
To post to this group, send email to qubes-users@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/qubes-users/134582e1-f89b-47d3-8176-68de4fd88851%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
[qubes-users] Re: Qubes 4.0 Documentation
-BEGIN PGP SIGNED MESSAGE-
Hash: SHA512
On 2018-01-25 12:28, awokd wrote:
> Resuming working my way through splitting up the documentation now
> that the 3.2 vs. 3.3 question has been mostly settled. Some
> general questions:
>
> 1. Should I open an issue for tracking and move the discussion
> over there? Move to qubes-devel? Keep here?
Please open an issue in qubes-issues.
(Doing so does not preclude discussion here or on qubes-devel.)
> 2. The command line tools in particular
> (https://www.qubes-os.org/doc/vm-tools/ and
> https://www.qubes-os.org/doc/dom0-tools/) seem Wrong to try to
> share the same pages for 3.2 and 4.0. Not only is the selection of
> commands slightly different between versions, but many have
> slightly different options ("-a" vs. "a"). I'm thinking of copying
> all the existing pages, appending "4" so they can be linked to
> directly, and putting in their own section. Thoughts?
Those pages are automatically generated from the man pages stored with
the tools' source code in their own respective repos, so any changes
to those pages in qubes-doc will be overwritten. Changes should be
made to the original files instead. That way, the changes will persist
when the qubes-doc versions are automatically generated.
I agree that the tool man pages should not be shared between 3.2 and
4.0 (but they probably wouldn't be anyway, due to the nature of the
system just described).
> 3. Some of these documents are pretty outdated. Should we have an
> Archive link and move stuff like
> https://www.qubes-os.org/doc/template/fedora/upgrade-18-to-20/ to
> it so it doesn't clutter up the main Docs page?
>
There are two categories of outdated documents:
1. Documents that we want updated (but that no one has updated yet).
2. Documents that are about old topics (but are otherwise good).
I don't think it would make sense to move documents of category 1 into
an archive section, since that would incorrectly suggest that we don't
want or expect them to be updated.
The old Fedora upgrade documents fall into category 2. However, it
looks like they (and perhaps the release notes for unsupported Qubes
versions) are the only major offenders visible in the main table of
contents. This is understandable, since a new version of the document
gets added each time there's a new version of the corresponding
software. I think it makes sense to handle these cases specifically,
by creating a page that collects all the versions of each one. I'll do
this now.
In general, it's worth thinking about whether we even want to keep
severely outdated category 2 documentation around. Does it have any
value anymore, or will it just produce misleading search results?
(Note that it will all remain permanently archived in the git revision
history, so it's mainly a question of visibility on the website.)
- --
Andrew David Wong (Axon)
Community Manager, Qubes OS
https://www.qubes-os.org
-BEGIN PGP SIGNATURE-
iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpqojUACgkQ203TvDlQ
MDDG4Q//Q6ND5fzToFv6KKQn4SzkcUSIIZQKtMPTlG9BkC7UCgjFZ+7sxrLA1N5X
H+9Z88+QNRL6FBOa6DHpFZOOA6vomzw0HXkTF+g9VcplsJIFZh6iB7lpSta1XwKU
1DG+ayF0oDd8PxKtSjaslMWRsr9p9cApPM7G+z6sGLB34LLZfolx19FRhwcpfBBK
09wyaAzmr5sF9oO8rSxC1llz5u75GatXUu+tHIc3Jh9C4hBtX7MSwyoq7eTkXnKQ
VpS35O8thmhm6cEuyNQsUD7ia853lWRcdTur1Am7GIx3jwl7VBQ6YCqanLRLueaI
tm4LbBfNrZcxFexHp0mB+veDeIfkC4cJZm8/sbjrHEicK6Cuvp5E0E6iLOaMw9gI
y3D1ypbEwMXyYQFPWW0h488pNow9RCrTHTcvBhgyIBw0xhCe0j89RZpbV3UB79k1
n5YRoj36XXRmHho/KVIlFMrzsXE6q9sawU8P1/Q7mBjX3fQLDoOEwFMtHRZTiFLk
NOkqv328xsqJy1smKgfFI4cpNMa1+Be0zGjqRWjBFNTqWEoNPkAbDbhbiwYPZYop
CW0lDS6b6dc2KCMcxlP+3BwuFC+pS9Yw/Qw2B0yceVjrH0YnLoVkOaqC6ojGx6DH
JAFtJLB6FbXssbK3JASOvGKpMxcktfQe3quJZmTaMY2yLkBaomA=
=8MfO
-END PGP SIGNATURE-
--
You received this message because you are subscribed to the Google Groups
"qubes-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to qubes-users+unsubscr...@googlegroups.com.
To post to this group, send email to qubes-users@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/qubes-users/fcd0e17f-4deb-cea5-b4f8-d62ea2a34b95%40qubes-os.org.
For more options, visit https://groups.google.com/d/optout.
