The thing I never got past with yjs was that the generalization of the todo app item-moving thing in this tutorial gets messy so quickly. If you have multiple objects that relate to each other, then you want them in the same Document, and keeping the relationships in sync has lots of gotchas (like needing the fractional indexing in the tutorial).

But then you accumulate a database worth of items and the simple toy model of putting everything into one document amounts to having to ship the whole DB (and it's history) to anything that wants to read any items. So you need to start breaking the items into separate objects and persisting them yourself, which has no documentation except for this tutorial [0] (spoiler alert: it's just an empty "Work in Progress - come back later" and has said that for years and years and years).

So you try to build a Provider to manage things, and the documentation story is the same [1].

Then you find out about Subdocuments and get happy that there's a solution to this common problem [2], but then learn that some Providers can't handle any relationships between subdocuments, and some Providers don't even support subdocuments, which goes back to issue of DIY providers not being documented.

So then you try to read some code to learn about it (after all, it's open source, we can't expect the dev to do all the work for us for free; let's do some work too!) and realize that what yjs really is at its core is a protocol. And that protocol -- the very essence of yjs -- is also totally undocumented and spread across a bunch of relatively idiosyncratic code. Unless you count a paper that documents how a yjs precursor worked a decade ago.

I didn't intend this to turn into a rant, but I've spent so much time trying to get it working over the years, and the gap between the toy 'Look it's magic!' demos and anything real is just so wide and the documentation for that part has been empty except "Work in Progress" for a decade.

I'm hopeful that some of the companies trying to monetize yjs, like the author of this post, are willing to step into that gap (which is who I'm writing this for, btw).

[0] https://docs.yjs.dev/tutorials/persisting-the-document-to-a-...

[1] https://docs.yjs.dev/tutorials/creating-a-custom-provider

[2] https://docs.yjs.dev/api/subdocuments

[3] I was really hoping that as I wrote this, the situation has changed, but it looks like all the documentation is just as WIP as five years ago and same for subdocument support.