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



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