-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 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 > documentation 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 > version Wait, why wouldn't 3.2 documentation be useful to anyone using 3.2? The majority of users are on 3.2 right now: https://www.qubes-os.org/statistics/ And 3.2.1 will be supported for a full year after the stable release of 4.0: https://www.qubes-os.org/news/2016/09/02/4-0-minimum-requirements-3-2-extended-support/ > 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. > http://qubes-os.org/doc/3/ or somesuch. > 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 documentation. > 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 >> page. > > 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. :) - -- Andrew David Wong (Axon) Community Manager, Qubes OS https://www.qubes-os.org -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpYN1sACgkQ203TvDlQ MDD2AxAAnPjscltdFLPYVZTapKJqiUiusiaeLdKaEDYUPRJzFJjovyL0cpzT0hFW o3x0ob6UTZNdy4ptpjn7mT3hYkzIL9zYatZfCdPIOnmzLVAZOSkCs0vwjjFE/U0N LGaU7CRWYcTAvGDM8QlF3JU8bAF24HUSDENpNBcluMWv19PHCshZpThKC4TwfWSH JdAoc8GBYfp3KagDAZab3p1XiPRLn2ZrCPTMpj4H1cSErhUJ1dUSOu10C9gu3jiB eaa/9tsqoEQZpwP0PE9NsIjNdNOnKVav0+1nHOU4cRiBWE/NTe8nA6vsW8P1gWOR VCRpB6upwYvv42NYIXuWBJEJw1wHIFiF44sS/0SRG58QboXVik1jTnjBQqRQ7z1s oRtTUsvoUyy5KP/5v4ODnlJ9LE64iHcXbZj2H00sSHSspHBOdzlJKPLr8W8ZhZ2M riDVUjPN+0iHUMBXrEfsyNBY+Wdk+7f3XI/mrWJVW0BIDPQOWuRa5QBk2RGNHXJP utC6yXlQK0T4u7CedEj8yp6FNW94N0fOjL1y1prSLZ6kbK+emfDD2gMYozO585u5 MOAkLujFv81MhI8EicuzEWeDRKlNIRNyqwdo/AG9yvq4cizzWIh51PXKMDEpjDBa FPP9wg34Vie2svD/SK7WghJgguLrYT3uM3z3M7HyPclqcFH92Lg= =ANlq -----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/fa165f07-ea98-81df-f1a5-d5949e47e556%40qubes-os.org. For more options, visit https://groups.google.com/d/optout.
