Clarify the mental model of the library

[tordans]

This is extracted from #405 and #404.

I think we can do a better job in explaining the mental model of the library in the readme.

My main disconnect is, that I always think about URL state libraries as using the URL as primary data store. This I how Geschichte https://github.com/BowlingX/geschichte works (AFAIK) and how manual URL state management via links/router.push would work.

Where here, we have a useState-Like interface that pushes the state to the URL "from time to time" (throttled) in order to allow navigation and URL sharing.

Just to be clear, I don't think there is anything wrong with this. It totally fine to work like this. It is just, that when you have a different mental model, you make wrong assumptions about how the library works.

Suggestion: I think the readme can do a better job to create the right mental model

For example

Simple: the URL is the source of truth

Is not really true, is it? It is true for the first render, when the URL is read. But the actual source of truth ist the useState-like state. The URL is mirrors this state asynchronously.

Like React.useState, but stored in the URL query string

Same here, where it is not really store but shadowed, maybe? Or preserved.

In general a short "How this library works" chapter on the readme would be a great idea, IMO.

[franky47]

Completely agree, and thanks for calling it out. The README is starting to become too bloated to properly convey all the possibilities this library now offers (hence the new docs on the roadmap), but the basic premises of how it works should be clear from the get go.