HELP WANTED: Lets improve the RxDB documentation

[pubkey]

In the RxDB user survey 2024 people voted that the documentation is the biggest drawback of RxDB.

So the plan is to rework all documentation pages in the next few weeks to make the better appealing to people that learn RxDB. And for that I need your help. Please give me some hints about:

• Which parts of the documentation are confusion to you?
• What was the hardest to learn when your started using RxDB?
• Which information is missing?

Please give me some feedback. You do not have to write the docs by yourself, just some hints are enough. You do not need to make big explanations.

Thank you 🙏

[jyling]

Hi, I used to struggle a lot on the Conflict handler before based on this link
https://rxdb.info/transactions-conflicts-revisions.html#custom-conflict-handler

While the basic function gave me an idea of how it would look, I'm unable to find the documentation about the conflict handler's second argument, which is remote.

it would be nice to have an explanation and sample on the second argument of the conflict handler which is the remote, since the conflict handler could be called many times.

so far I am aware that these are the few possible values the remote argument will provide based on the RxDB source code. but a detailed explanation of each of the values will be helpful for newcomers and existing ones.

• replication-resolve-conflict
• upstream-check-if-equal
• downstream-check-if-equal-0
• downstream-check-if-equal-1

of course, It could also be my mistake, the documentation is there but I just didn't see it.

Thank you.

[troywweber7]

This is minor, but I think one thing I and my company struggled on a lot was our first time setting up replication. I wouldn't say the documentation was bad, it was more that some of the documentation examples felt incomplete or maybe had typos that caused a little confusion when trying to connect the dots for the first time. It also took me a while to realize that before reading the graphql replication documentation, I should probably have read the general replication documentation first.

My company still needs to dig into better conflict handling, schema versioning and migration, and paid plugins, but overall we intend to continue using RxDB.

[enrico-teterra-maramalabs]

Hey! I've been working with migrations recently and found the migration-schema documentation very helpful. All the information is on the page there, but it's difficult to understand at a glance what is relevant

I think the structure could be improved to make the key information more accessible. For example I initially skipped over sections like autoMigrate and migrationStates because I wasn’t sure what they were or if they were important

I also think "migration strategies" sound complicated and could maybe just be called migration functions

What about something like this:

• Introduction
• Installation
• Getting Started

Advanced Use Cases

• Async migrations
• Filtering documents
• Migrating attachments

Choosing When the Migration Runs

• Automatic (default)
• Manual

Frequent Questions

• Do migrations work with multiple tabs?
• Do migrations work with replication?

---

I made the following assumptions:

• first-time visitors will only read up to getting started
• second-time visitors will read about any important choices they need to make
• third-time+ visitors will read a few more sections, but only if they seem relevant to a question or problem they have

I think other pages in the docs could also benefit from a similar restructure/rewrite

[robinduerhager]

I just looked at the docs to see if RxDB would fit my needs. During my research for using attachments I saw that neither in the Attachments section nor in the Replication Protocol section, there was a table that states which replication plugin (or which overall configuration) supports attachments.

Since it states in Replication Protocol that "However not all replication plugins support it.", i think this would be beneficial to immediately identify which plugins (or configuration in general) would fit ones needs :).

[mattriese]

I would appreciate pretty diagrams like some other options have. It both makes it easier to orient your thinking when learning how the library works, it also makes the project seem more professional and legitimate.

for example, see all the diagrams on this page: https://docs.powersync.com/overview/readme-1

[fadnincx]

I would appreciate multiple layers of depth of the documentation of the replication. As I feel this is where one often interacts with custom code/other software that needs to be adopted to rxdb. Especially since each replication plugin is different.

For me, for example having a custom webrtc replication endpoint (in golang) requires a lot of reverse engineering on all the small implementation details before coming even close to the concepts mentioned in the documentation.

[lavaxun]

Thank you for the great work on the project! I have a few suggestions that might enhance the developer experience (DX) with the documentation.

It would be really helpful if more examples could be provided, especially with some illustrations or diagrams. For instance, for the sync-related lifecycle events such as awaitInitialReplication and awaitInSync, having more visual aids could make the behavior and flow clearer. Similarly, the resync behavior feels a bit like a black box at the moment. Visual explanations of when specific events are triggered would go a long way in clarifying how things work behind the scenes.

For reference, I’ve attached a couple of sample diagrams that I found helpful from another project:

Credit: Cloud Theodo Blog

Additionally, here are a few more areas where further examples or elaboration could be beneficial:

1. Conflict handling.
2. Local document management.
3. RemoteRxStorage.

Once again, thank you for your hard work. These suggestions are just some thoughts on how the documentation could be even more developer-friendly.

[tsekiguchi]

This is a worthy project, and I commend you for taking this on! I love RxDB, and I can't wait for others to be able to learn about and use it too.

When I was getting started using RxDB, there is SO MUCH great documentation, and you certainly have already written in detail about a lot of the questions that I had along the way. I personally felt like one of my biggest speed bumps was the structure of the topics in the left bar. I felt like they could be condensed and recategorized into more drop downs (like Migration and Server) so that information is easier to find. For instance, on the left hand side, after Migration, it feels like you've started to list a lot of features / topics that are important but they are kind of just added on and have no cohesion.

Also there's also a lot incredible information that you've put down in Articles that could be categorized with the relevant section so that people understand that there is more to read, and which topics those articles are related to. Just an idea - you could add a section at the end of RxDocuments called "Further Reading" that links to relevant articles, like attachments, migrations, etc.

As a somewhat new user who has just taken the hours to go through all the documentation you've written, I know that I'd be a great tester for clarity and organization! I would be genuinely more than happy to assist in any way that I can with this, whether that's coming up with visuals diagrams, proof reading individual pages for clarity, further help with organization, or anything else.

Thank you!

[brunovinicius]

I found out that Angular PWA service worker tries to cache, intercept and respond to GraphQL requests and although throughout the tests it didn't seems to cause any issues, when we went to prod we found out it was causing inconsistency on the data synced between clients (some documents missing on the local DB; distinct sets between them). Besides that we found out that it also duplicated pushes especially after recovering from offline or after refreshing an expired auth token.

If you can see how this might cause issues, I would say its probably a good idea to add a warning box to the documentation calling attention to the fact.

We added a header to our requests as documented on the link below, and it seemed to improve stability substantially.

https://angular.dev/ecosystem/service-workers/devops#bypassing-the-service-worker

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed soon. Please update it or it may be closed to keep our repository organized. The best way is to add some more information or make a pull request with a test case. Also you might get help in fixing it at the RxDB Community Chat If you know you will continue working on this, just write any message to the issue (like "ping") to remove the stale tag.

[pubkey]

ping

[yashspr]

Thanks a lot of taking the initiative to improve the documentation. And, thanks a ton for building this amazing library. I have been building an offline first app, for which the replication module in this library is critical. Based on my usage so far, here are my suggestions:

1. More information on the flow of the replication. For example, when is the pull handler called, and when is the push handler called, what happens if there is a conflict from the pull handler, what happens when there is conflict from the push handler.

2. In continuation to point 1, what are the arguements to the conflict handler (assumed master state, real master state, new document state). I noticed during testing that the "assumed master state" which is passed to the conflict handler is sometimes present, but other times null. Why is that so?

To summarize, just providing more detailed information on replication protocol and the conflict handler and its flow would be of immese help.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed soon. Please update it or it may be closed to keep our repository organized. The best way is to add some more information or make a pull request with a test case. Also you might get help in fixing it at the RxDB Community Chat If you know you will continue working on this, just write any message to the issue (like "ping") to remove the stale tag.

[pubkey]

Ping