-----BEGIN PGP SIGNED MESSAGE-----
On 2018-01-11 16:11, 'Tom Zander' via qubes-users wrote:
> On Thursday, 11 January 2018 18:16:04 GMT Unman wrote:
>> On the VPN case your own comment confirms that it would be
>> better to provide a separate section, rather than trying to put
>> "exceptions" in to the existing text.
> Thank you for explaining that unman, much clearer indeed.
> While I agree on the general statement above, I feel its not the
> best solution in this case where 4.0 have massive changes in all
> layers of the technology.
A lot of changes, sure, but I wonder whether there are more
similarities than differences overall (thinking about fundamental
things like the use of Xen and TemplateVMs).
> In many cases the about half of the text will be duplicated
> between the 3.2 and the 4.x sections, albeit with major changes.
> This will not help the reader much.
Why is that? Just because many docs will be longer, since they'll have
a section for 3.2 and a section for 4.0?
> More importantly, I fear that the new users (potential
> contributors) that have not used 3.2 will have a hard time
> deciding what to do with information that clearly doesn't represent
> the current state of technology.
Why will this be a problem? If the section is clearly labeled "Qubes
3.2," but they use 4.0, are you concerned that they won't realize the
section doesn't apply to them? If they can't make that distinction,
though, why expect them to be any more successful at distinguishing
between two sets docs?
> Asking people to put a lot of effort into reformatting
It shouldn't require much effort. In most cases, all you have to add
is `## Qubes 3.2` above the existing documentation, shift the rest
of the headers down one by adding a `#` in front of each one, then add
`## Qubes 4.0` above the 4.0 content you want to add. It might be
slightly trickier if the current headings use the underlining syntax.
This requires basic familiarity with Markdown, but that's already
required for most doc contributions. Only one person has to do this
for each document, and many documents will not even require this
because the content applies to both 3.2 and 4.0.
> that may or may not actually be useful to anyone using an older
Wait, why wouldn't 3.2 documentation be useful to anyone using 3.2?
The majority of users are on 3.2 right now:
And 3.2.1 will be supported for a full year after the stable release
> is a big ask in a volunteer project.
>> I personally prefer the solution where a git repo is cloned for
>> 3.2 as
> "legacy" which is then attached to the website under a
> subdirectory and people can edit that for maintainance and fixes.
If I understand this proposal correctly, all the current documentation
would initially exist in the 4.0 documentation set. But a lot of it,
as you've pointed out, only applies to 3.2. So, who's going to go
through and remove all the content that no longer applies in 4.0?
That's a lot more difficult than formatting a few headings, so it
strikes me as a much bigger ask.
Alternatively, we could start with an empty directory for 4.0. Then
no one has to sort through all the 3.2 documentation to see what still
applies. But now we have an even bigger problem: *all* the
documentation has to be written (or selectively copy/pasted)! This
seems like an even bigger ask the previous one.
Is there some third way you have in mind that I'm missing?
> The majority of changes would then be in the 'master' branch which
> people can edit and they can add references to the github issues
> concerning known bugs. We can mark known issues with the pages
> like the VPN one I described and people reading the docs will
> actually be aware of pitt-falls.
You can (and are encouraged) to do exactly this under the current
system. There's nothing stopping you from doing this, and there are a
lot of examples where this has already been done in the existing
> In my opinion there is only one thing worse than no documentation,
> it is official looking documentation that is wrong.
I agree, but I don't see why having clearly-labeled sections where
there are version differences would result in this. If there's some
official documentation in a section called "Qubes 3.2," it's not
"wrong." It applies to 3.2.
Maybe the concern is that, *before* someone gets around to adding the
"Qubes 3.2" heading, a 4.0 user will see it and be misled. That's a
legitimate concern, but how would your alternative proposal avoid it?
If we simply clone the documentation into two separate sets -- one for
3.2 and one for 4.0 -- we have the exact same problem. The 4.0 clone
still has stuff in it that's only true in 3.2, and until someone gets
around to deleting it, a 4.0 user who sees it could be misled. Am I
missing something here?
>> Also, that once 3.0 is retired, it will be simple to remove the
>> 3.0 relevant material, rather than filleting our bits from each
> This would be even better, if qubes ever wants to they can just
> remove the subrepository.
> What do others think?
If there turn out to be significant, compelling reasons to make
completely separate sets of docs (one for 3.2 and one for 4.x), of
course I'd be happy to do that. We should weigh the costs and
benefits, and choose whichever system is best. From a maintainability
perspective, it seems simpler and easier just to have a single set of
docs, and that's what Qubes has always had, so that's why it's the
default system right now. That's not set in stone, but I think an
alternative system should deliver significant benefits for it
be worthwhile for us to move from the default system. So far, it seems
like the objections to sticking with the default system and simply
having separate sections within the existing docs rest on
misunderstandings about how that system would work, but I'd be
happy to be convinced otherwise. :)
-----END PGP SIGNATURE-----