Documentation improvement suggestion for Runes DEEP state section.

[peterhoward42]

Describe the problem

The documentation section on Runes Deep State is quite hard to understand.
Specifically it seems from the conversation in this Reddit thread , that many people fail to grasp after reading it, what the benefits or relevance of it is. I didn't get it straight away, but was overjoyed when I realised how useful it was.

https://www.reddit.com/r/sveltejs/comments/1hwtaki/runes_are_a_great_improvement_over_stores/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button

Describe the proposed solution

To have a preliminary section that introduces the topic with a message that follows the pattern "if you want to achieve this, then deep state can help you like this...". (I believe that an active-voice introduction will pull the reader into the topic).

To illustrate:

"The DEEP STATE capabilities of Runes $(state) help, when you have for example a Component composed of several related sub components which conceptually all use a data model in common, and where changes to the state in one might need to ripple or propagate changes to the others. In this case you can define a single rune $state object as the data model that can be shared (imported) into all the components that want it. With this arrangement any change to any field in that object will trigger reactivity in all the consumers of that field. It's called DEEP because changes propagate up from the fields to the parent object. And it works (recursively) if you nest objects - which lets you craft a well structured view model". It also helps you to manage the interplay logic in the data model in a dedicated place, leaving the components to focus on rendering the view.

Importance

nice to have

[Inqnuam]

I’d also like to know more about $derived. For example, can we change the nested value of a $derived state? Is that considered good or bad practice? A section titled something like Best Practices would be incredibly helpful for many of us.

For the past two months, I’ve been migrating a complex app from Svelte 4 to Svelte 5, and I’ve found the official documentation about runes somewhat lacking. I often have to rely on a trial-and-error approach, which consumes a lot of time.

That said, I want to express my gratitude to all the Svelte developers and bug reporters. Svelte 5 keeps getting better and better! ❤️

[StevenStavrakis]

I think generally that the svelte team should be more prescriptive regarding what are good practices and bad practices and how to use runes to solve interesting problems. I know that is teetering on being outside the scope of the maintainer's responsibilities, but I want to see what they see when they look at runes.

It is a fundamentally new paradigm in development and could benefit from explanation and examples maintained by the people that built it.

It is worth mentioning that this would usually be in the tutorial instead of the docs.