Re: [PATCH] Documentation: reword the distinctive feature of shared state

[Alyssa Ross <hi@alyssa.is>]

[-- Attachment #1: Type: text/plain, Size: 3676 bytes --]

Valentin Gagarin <valentin@gagarin.work> writes:

> This changes front-page wording in load-bearing ways, for reasons that
> may be non-obvious:

Wow, I love the explanation/diff ratio here!

> - Split into shorter sentences
>
>   Each one is focused on describing a separate idea.  The second idea is
>   more complex and warrants more words, so having a dedicated sentence
>   avoids losing the reader.
>
> - s/several dozen/many/
>
>   The particular number doesn't matter, and may be arbitrarily wrong in
>   practice.  The point is that there's fragmentation.  The snark about
>   any large number is unnecessary if we put the real problem in the
>   foreground.
>
> - s/mixed up in//
>
>   It could be that entanglement is an issue, but fragmentation seems to
>   be the bigger issue.  In any case, the original sentence was awkward
>   grammatically, because it tried putting together how a system is
>   handled with what the system is like.
>
> - s/managed as a whole/still treated as a whole/
>
>   We're already saying "managed" in the first sentence.  Managing
>   the system is very different from managing state.  We need to be
>   careful with using words without prior definitions, so the best we can
>   do here is avoid inadvertent conflation.  There is enough potential
>   for confusion as it is.
>
>   "still" acknowledges the traditional single-system experience that
>   Spectrum preserves by design.

The "still" appears to have got lost from the actual diff.  Should I put
it back in?

> - s/backed up and//
>
>   The difficulty of backing up is a specific instance of the
>   fragmentation problem.  But this is likely only evident to Qubes
>   users.  We can expect most readers to know about it theoretically at
>   best.  While it's not wrong to have this sort of anchor, keeping it
>   risks diluting the main message.

I'm concerned that removing the more specific verbs here might make it
more difficult to understand /why/ treating the system as a whole is
desirable.  We don't have to be so specific as to call out backups or
management, but I think without talking about something more specific,
even if that's just "thinking", as in "one only needs to think about a
single system", it loses its motivation.

> - "each becoming a system of its own"
>
>   This captures the Qubes failure mode Spectrum avoids, where per-VM state
>   accumulation forces operators into what amounts to orchestrating
>   a cluster on one's desktop.
>
>   In the original, the contrast to Qubes would not be as strong for
>   people only familiar with it superficially.  Being more explicit about
>   the nature of the problem helps establishing the narrative frame and
>   original motivation of Spectrum early on, part of which is overcoming
>   Qubes limitations.

Missing Signed-off-by.

> ---
>  Documentation/index.html | 6 +++---
>  1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/index.html b/Documentation/index.html
> index 6d6faf7..0ea0a2f 100644
> --- a/Documentation/index.html
> +++ b/Documentation/index.html
> @@ -23,9 +23,9 @@ such systems.
>  
>  <p>
>  User data and application state will be managed centrally, while
> -remaining isolated, meaning that the system can be backed up and
> -managed as a whole, rather than mixed up in several dozen virtual
> -machines.
> +remaining isolated.  This means that the system can be
> +treated as a whole, rather than many virtual
> +machines each becoming a system of its own.
>  
>  <p>
>  Spectrum is an upstream-first project.  Wherever possible, we aim to
> -- 
> 2.54.0

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 227 bytes --]