-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 On 2018-01-11 22:23, Chris Laprise wrote: > On 01/11/2018 10:31 PM, Andrew David Wong wrote: >> On 2018-01-11 14:41, Chris Laprise wrote: >>> >>> At least no section repetition for the scripts should be >>> necessary. But doing this for the dialogs still adds a lot to >>> an already long doc. >>> >> >> Is it bad for a doc to be long when it's immediately obvious >> which half you can ignore because it's not the version you're >> using? > > Not necessarily for a reader, except in the case where the > instructions are long to begin with and the reader happens to > scroll into the section for a different version... without a > floating page element that always keeps the heading visible, the > reader might inadvertently mix directions from the two > version-sections. > >> >>> I feel that, apart from making some docs look deceptively long >>> and less readable, the most significant downside to melding >>> 3.x/4.x instructions together would be to discourage >>> contributions from users. It makes the thought of every >>> potential edit seem like a slog through extra markdown, and >>> many will think "I don't have time to install 3.2 to write up >>> that version". >>> >> >> I don't understand. Why would this be the case? If you want to >> make a small edit that pertains only to 4.0, you can simply make >> that small edit in the 4.0 section, or add such a section if one >> doesn't yet exist, which would only be a few extra characters. A >> 4.0 user who wants to add some true fact about 4.0 to the docs >> doesn't even have to think about 3.2, much less install it. > > If they don't have to think about 3.2, that's fine. But I'd expect > queries/requests for "3.2 version" would appear in the PRs about > some new fixes, info or approaches the users are trying to > introduce into the document(s). > > Making an edit "that pertains only to 4.0" isn't going to be the > mental context of the user-contributor in most cases. They will > just have new info that they are unsure whether it applies to 3.2 > (or if it does, how). And I'm sure even advanced users will be > feeling the uncertainty and friction before long. >
Wouldn't the same problem apply if there were two sets of docs? They'd have to make the same decision about whether to add it only to the 4.0 docs or also to the 3.2 docs. In that situation, it seems more likely that they would simply ignore (or not even think of) the 3.2 docs. Out of sight, out of mind. But then the value proposition of having two sets of docs really just comes down to saying, "It's hard for contributors to ignore a section called 'Qubes 3.2' when they're on 4.0. Let's make it easy for them by moving that to a different doc." That seems kind of uncharitable to our contributors. We'd also tend to lose out on contributions that apply to both 3.2 and 4.0. Suppose someone *is* familiar with both versions and adds some valuable content that's true of both versions. If they, too, forget that the 3.2 docs exist, that's a loss. > Tom Zander makes some good points, too. > > OTOH, I don't want to belabor the issue -- and I'm far from > certain anyway, this is about psychology. > Neither do I. I just want to make sure that we think things through, and that the costs are really worth the benefits, before jumping into a new system. - -- Andrew David Wong (Axon) Community Manager, Qubes OS https://www.qubes-os.org -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEEZQ7rCYX0j3henGH1203TvDlQMDAFAlpYPLQACgkQ203TvDlQ MDChARAAr+BQwC2lvsjaTERhAwOx0DpuPy3JDhEzUDuQ0pT2dvXp7Lq8bk7DXhA/ 5QQyyKO2NyNLuPOFCrBvel719iFzIN378w42gbDHFx8z0Torg+XN6YbuCQhQ/zGs yZG6zHj87HJOD6z3l82nH/FtZQrtg8iCeHrLomW9DYNso0bO6RLvyxZDR0uk3Q58 ++/D0OEDozbTWlsuFR/Yef9cWQbsh9BGreRmF6qkgdrYzzAygUJaFYMdKdIgvByN P4JZQq4GWp2GjetpFMw2Nc2v1u6aE7u6XHcdykOD2QF9oggx35eBuYWgvnD5hJd3 HZ/xSbY5LtFxny7FoMQgFcrwtbHbOL6RuaK7N2rXzl8G1sXkxgF9gLaFe12zGD1O QKofza5UqjQxYMvXC74hL2+eCJGnwyfnEpX+91uw36ku/54P1vbzAfcVxfDbDX79 gF2jC+adSN8E/SC1+nhmkff8SLsuyHwPJxPyZrth9RXPm9CyVNaR7v38WEnjnYAM AWatWYWX1J+nGp939A+OoeOR0sO7lFNq/3QYfCRAtaCRIkrOYH+hKvdEUlVJNj+U quKiO6UZ/ObzSLyhYbpz1rCmdQWhpVcM4Pr7s5DYHcR3v+VDrPV8TjIqbJthkZWF t29NZsu/AZ18UuvSG1wC1DcRfM5DbUXaEOoVmzG10k+QZbCinXw= =LcZz -----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/e27af887-4aa1-9287-d605-b29e536f974a%40qubes-os.org. For more options, visit https://groups.google.com/d/optout.
