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



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 
For more options, visit https://groups.google.com/d/optout.

Reply via email to