[docs] update intro sentence of reactive declarations tutorial

[simondao]

The sentence "Often, some parts of a component's state need to be computed from other parts (such as a fullname derived from a firstname and a lastname), and recomputed whenever they change." was very confusing and also grammatically incorrect because "and recomputed whenever they change" is a dependent clause.

According to Grammarly, "A dependent clause is a clause that cannot stand as a sentence in its own right, such as before I left the parking lot. When a complex sentence contains a dependent clause like this one, a comma is not used unless the dependent clause comes before the independent clause."

https://www.grammarly.com/blog/comma-in-complex-sentences/#:~:text=A%20dependent%20clause%20is%20a,comes%20before%20the%20independent%20clause.

Before submitting the PR, please make sure you do the following

• It's really useful if your PR references an issue where it is discussed ahead of time. In many cases, features are absent for a reason. For large changes, please create an RFC: https://github.com/sveltejs/rfcs
• Prefix your PR title with [feat], [fix], [chore], or [docs].
• This message body should clearly illustrate what problems it solves.
• Ideally, include a test that fails without this PR but passes with it.

Tests

• Run the tests with npm test and lint the project with npm run lint

[benmccann]

I think it was better before. Though I agree the comma in the prior text was not necessary and would be fine removing it. I think now it has become much more verbose to say the same thing. The verbosity in this case, in my opinion, makes it harder to follow.

I think the fullname, firstname, lastname example maybe could even be removed altogether because the code example uses doubled and count. It doesn't really add much to have two examples and I think might just confuse things to have the text and code block using different variables

[simondao]

Besides the grammar error, the “they” in the phrase “and recomputed whenever they change” can reference either “some parts” or “other parts”. Without carefully studying the example, the reader cannot tell which was the intended target. When such ambiguity exists, it’s an indicator that the writer has probably prioritized tenseness versus clarity. My suggestion is clarity over terseness. Another way to think about it: if a piece of text introduces ambiguity such that it’s not understandable without an example, it’s probably shouldn’t be written.

…

On Sat, Apr 23, 2022 at 1:17 PM Ben McCann ***@***.***> wrote: I think it was better before. Though I agree the comma in the prior text was not necessary and would be fine removing it. I think now it has become much more verbose to say the same thing. The verbosity in this case, in my opinion, makes it harder to follow. I think the fullname, firstname, lastname example maybe could even be removed altogether because the code example uses doubled and count. It doesn't really add much to have two examples and I think might just confuse things to have the text and code block using different variables — Reply to this email directly, view it on GitHub <#7467 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAVFL3DNRZAF2VKTA7UDTZDVGQ5B3ANCNFSM5TSZJNUQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[benmccann]

I think the "and also want to recompute fullname when firstname and/or lastname changes" is unnecessary as the recomputation is implied by the word "derived". The "and/" is unnecessary since firstname and lastname aren't updated atomically. And the "For these" portion no longer reads correctly as it's a new sentence preceding it.

More importantly, I think the whole text is a distraction. It's going off describing what derived state is using an example that's different than the one used on the page.

How about something like this?

---

Svelte automatically updates the DOM when your component's state changes. It can also update derived state automatically with reactive declarations.

Here's an example where the derived variable doubled will be automatically updated:

let count = 0;
$: doubled = count * 2;

[simondao]

That’s a great suggestion. It might come with a subtle issue for folks new to svelte: it introduces the notion of a “component's state” without defining what that means.

…

On Sun, Apr 24, 2022 at 9:38 PM Ben McCann ***@***.***> wrote: I think the "and also want to recompute fullname when firstname and/or lastname changes" is unnecessary as the recomputation is implied by the word "derived". The "and/" is unnecessary since firstname and lastname aren't updated atomically. And the "For these" portion no longer reads correctly as it's a new sentence preceding it. More importantly, I think the whole text is a distraction. It's going off describing what derived state is using an example that's different than the one used on the page. How about something like this? ------------------------------ Svelte automatically updates the DOM when your component's state changes. It can also update derived state automatically with *reactive declarations*. Here's an example where the derived variable doubled will be automatically updated: let count = 0; $: doubled = count * 2; — Reply to this email directly, view it on GitHub <#7467 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAVFL3AAY2AVEQIK47LVOHLVGYAR7ANCNFSM5TSZJNUQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>

[simondao]

How about this...that uses similar language from the previous tutorial exercise: Svelte's system of reactivity not only keeps the DOM in sync with your application's variables as shown in the previous section, it can also keep variables in sync with each other. For these, we have...[continue as written in current version]

…

On Mon, Apr 25, 2022 at 9:26 AM Simon Dao ***@***.***> wrote: That’s a great suggestion. It might come with a subtle issue for folks new to svelte: it introduces the notion of a “component's state” without defining what that means. On Sun, Apr 24, 2022 at 9:38 PM Ben McCann ***@***.***> wrote: > I think the "and also want to recompute fullname when firstname and/or > lastname changes" is unnecessary as the recomputation is implied by the > word "derived". The "and/" is unnecessary since firstname and lastname > aren't updated atomically. And the "For these" portion no longer reads > correctly as it's a new sentence preceding it. > > More importantly, I think the whole text is a distraction. It's going off > describing what derived state is using an example that's different than the > one used on the page. > > How about something like this? > ------------------------------ > > Svelte automatically updates the DOM when your component's state changes. > It can also update derived state automatically with *reactive > declarations*. > > Here's an example where the derived variable doubled will be > automatically updated: > > let count = 0; > $: doubled = count * 2; > > — > Reply to this email directly, view it on GitHub > <#7467 (comment)>, > or unsubscribe > <https://github.com/notifications/unsubscribe-auth/AAVFL3AAY2AVEQIK47LVOHLVGYAR7ANCNFSM5TSZJNUQ> > . > You are receiving this because you authored the thread.Message ID: > ***@***.***> >

[benmccann]

Sure, that mostly sounds good to me. I think we'd need to update the following sentence slightly and I'd drop "system of". With those changes it could look like:

Svelte's reactivity not only keeps the DOM in sync with your application's variables as shown in the previous section, it can also keep variables in sync with each other using reactive declarations. They look like this:

[simondao]

That’s perfect!!!

…

On Fri, May 6, 2022 at 11:01 AM Ben McCann ***@***.***> wrote: Sure, that mostly sounds good to me. I think we'd need to update the following sentence slightly and I'd drop "system of". With those changes it could look like: Svelte's reactivity not only keeps the DOM in sync with your application's variables as shown in the previous section, it can also keep variables in sync with each other using *reactive declarations*. They look like this: — Reply to this email directly, view it on GitHub <#7467 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAVFL3C4AFBFXNKQUPC6K23VIU633ANCNFSM5TSZJNUQ> . You are receiving this because you authored the thread.Message ID: ***@***.***>