Re: [PATCH v2 1/2] Documentation: reword the distinctive feature of shared state

[Alyssa Ross <hi@alyssa.is>]

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

Valentin Gagarin <valentin@gagarin.work> writes:

> This changes front-page wording in load-bearing ways, for reasons that
> may be non-obvious.
>
> The overarching idea is to reduce the textual surface area, for instance
> by replacing arbitrary examples with subsuming terms, while
> staying very specific with what is to be conveyed and where possible
> making it more relatable to the intended audience.
>
> - 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/User data and application state/Persistent data/
>
>   The focus of the sentence is the central management.  By being a bit
>   more general while technically still very specific (all persistent
>   data is the same from the perspective of the system) we save the
>   attention for the important part.
>
> - s/remaining isolated/applications remain isolated/
>
>   The data being isolated never made sense; it's the applications'
>   access to it that is isolated. The phrasing chosen is more compact but
>   still correct, and leaves room for expanding on the isolation in
>   a separate paragraph.
>
> - 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.
>
> - 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.
>
> - "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.
>
> Signed-off-by: Valentin Gagarin <valentin@gagarin.work>
> ---
>  Documentation/index.html | 8 ++++----
>  1 file changed, 4 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/index.html b/Documentation/index.html
> index a717d2c..6d4f07b 100644
> --- a/Documentation/index.html
> +++ b/Documentation/index.html
> @@ -22,10 +22,10 @@ lower barrier to entry and to be easier to use and maintain than other
>  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.
> +Persistent data will be managed centrally, while
> +applications remain isolated. This means that the system can still be
> +thought of as a whole, rather than many virtual
> +machines each becoming a system of its own.

I'm convinced, I think.  Lines are a bit ragged though so I'll rewrap
when applying.

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