Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

HELP WANTED: Lets improve the RxDB documentation #6473

Open
pubkey opened this issue Oct 7, 2024 · 18 comments
Open

HELP WANTED: Lets improve the RxDB documentation #6473

pubkey opened this issue Oct 7, 2024 · 18 comments

Comments

@pubkey
Copy link
Owner

pubkey commented Oct 7, 2024

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
Copy link

jyling commented Oct 7, 2024

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
Copy link

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
Copy link

enrico-teterra-maramalabs commented Oct 7, 2024

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
Copy link

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
Copy link

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
Copy link

fadnincx commented Oct 9, 2024

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
Copy link

lavaxun commented Oct 15, 2024

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:

image
image
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
Copy link

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
Copy link

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

Copy link

stale bot commented Oct 25, 2024

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.

@stale stale bot added the stale label Oct 25, 2024
@pubkey
Copy link
Owner Author

pubkey commented Oct 25, 2024

ping

@stale stale bot removed the stale label Oct 25, 2024
@yashspr
Copy link

yashspr commented Oct 25, 2024

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.

Copy link

stale bot commented Nov 1, 2024

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.

@stale stale bot added the stale label Nov 1, 2024
@pubkey
Copy link
Owner Author

pubkey commented Nov 2, 2024

Ping

@pubkey pubkey removed the stale label Nov 15, 2024
Copy link

stale bot commented Nov 22, 2024

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.

@stale stale bot added the stale label Nov 22, 2024
@pubkey pubkey added never-stale and removed stale labels Nov 23, 2024
@gerardnll
Copy link

Hi! RxDB is such a great project and it's been so useful, I'm looking forward to go premium once I've done all the implementation. I've found some issues trying to do the following things and it's been difficult to find how to do them properly:

  • How to 'truncate' collections but leave schema and everything intact. Is that possible? There are many functions but they are not clear enough for me. For example, I have N events and those events have N attendees. If I change active event, i want to clear the attendees collection so I can load the attendees for the next selected event. Should I create a DB for event? I don't want to leave traces everytime I change event.
  • Is there a way to get information about replication/sync state? Changes not synced, syncing in progress, etc.
  • Improve categorization of left bar topics.

@pubkey
Copy link
Owner Author

pubkey commented Nov 27, 2024

@tsekiguchi
Copy link

tsekiguchi commented Dec 17, 2024

Hi @pubkey et al,

I wanted to post here a first pass at the Table of Contents (sidebar) organization. Now that I'm pretty familiar with all the docs, I felt like placing information into some big buckets could help new users understand RxDB more quickly and more in depth, and help current users find what they're looking for.

I've included all the items that you currently have in the sidebar, renamed a few for clarity, and suggested a couple new pages that might be useful.

Let me know what you think!

Getting Started with RxDB

  • Introduction
  • Quickstart
  • Installation
  • Development (renamed from Dev-Mode Plugin)
  • Node.js Tutorial

Why RxDB

  • Empowering Web Applications with Reactive Data Handling
  • The Benefits of Browser Databases and RxDB
  • Local First / Offline First (article)
  • Downsides of Local First / Offline First
  • Why NOSQL
  • Alternatives

Releases

How RxDB Works

  • Database Storage Architecture (renamed from RxStorage Layer)
  • Transactions, Conflicts, & Revisions
  • Replication Protocol
  • What is a realtime database?
  • JSON Database
  • In Memory

RxDB Architecture

  • RxStorage (free listed first, premium second)
    • Dexie.js
    • MongoDB
    • DenoKV
    • FoundationDB
    • LokiJS
    • Remote
    • Memory
    • IndexedDB
    • Memory
    • SQLite
    • Performance Comparisons (renamed from article, ‘LocalStorage vs. IndexedDB vs. Cookies vs. OPFS vs. WASM-SQLite’)
  • Wrappers and Plugins
    • Workers
    • SharedWorkers
    • Encryption
    • Key Compression
    • Memory Mapped
    • Memory Synced
    • Sharding
    • Leader Election
    • Localstorage Meta Optimizer
    • CRDT
    • Electron
    • Create a plugin
  • RxDatabase
  • RxSchema & Collections
    • Schema Validation
    • Typescript Types
  • RxDocument
    • Operations, including populate (which is currently its own page)
  • Attachments
  • Queries

RxDB Features

  • Migrations
    • Schema Migration
    • Adding Fields to your Schema (new page or section)
    • Storage Migration
  • Pipelines
  • Observables (new page)
  • Schema Validation
  • Cleanup
  • Backup
  • Encryption
  • Key Compression
  • Signals & Custom Reactivity
  • RxState
  • Local Documents
  • Hooks (renamed from Middleware)
  • Query Cache
  • Full Text Search
  • Query Optimizer
  • Logger
  • RxServer
    • RxServer
    • Scaling

RxReplication

  • HTTP Replication
  • RxDB Server Replication
  • GraphQL Replication
  • WebSocket Replication
  • CouchDB Replication
  • WebRTC Replication
  • Firestore Replication
  • NATS Replication

Examples

  • Embedded Database
  • Flutter
  • Mobile
  • Javascript FE Database
  • PWA
  • React
  • Capacitor
  • Electron
  • Ionic

Performance Comparisons

  • Benchmarks
  • Optimizations (new page that talks about strategies for getting the most out of RxDB)
  • Why IndexedDB is slow
  • WebSockets vs Server-Sent-Events vs Long-Polling vs WebRTC vs WebTransport

FAQ

Contribute

Contact

  • Consulting
  • Discord
  • Email
  • Chat

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests