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

Reply via email to