Store documentation and tutorial

[rlaferla]

The tutorial for stores uses an integer count in the example. It doesn't talk about other values like whether or not we can put objects/dictionaries in a store. It doesn't explain the writable() syntax.

[joakim]

I agree that stores could be explained better in the API docs. It is after all a fairly simple concept, but for a newcomer to Svelte it's not that obvious how stores work and how one should use them.

In the API docs, svelte/store links to a low-level explanation of how stores are implemented with a rudimentary $count example. But it's easy to get confused if "stores" make you think of managing state in a single app-level megastore.

I found this RFC useful to better understand Svelte 3's stores. Especially this line:

Essentially, the shift is from a single observable store of values to multiple observable values.

I think that should be explained up-front so the reader has the right idea of what a store is before diving in.

I also think it would help to have more real-world examples of how stores should be used. When Svelte gets a cookbook page/site one could link to recipes there. Until then, a more substantial example than $count would be helpful, or maybe links to relevant parts of the tutorial.

[joakim]

In general, I think the API would benefit from linking more to the tutorial and examples. Something like this:

I'd be happy to make a PR for that if the maintainers are positive to something like this.

[mindrones]

I agree some interlinking would be nice but for that I'd open another issue with a table of correspondences like:

API section	tutorial	example	notes
writable	writable-stores	writable-stores	missing features x, overlaps with y
section A	missing	link
section B	link 1	link	incomplete
	link 2		duplicate
section C	link	link

so that we can evaluate how many links we would have to add and what's missing.

[joakim]

OK, I'll have a look at that when I have the time!

[mindrones]

@joakim following this discussion I've opened #3719

[pngwn]

Duplicate of #3053 .