Help us migrate & improve 🍉 documentation

[radex]

Hey,

I'd like to migrate WatermelonDB docs from mdbook to Docusaurus, a de facto standard in the React/React Native community for project websites. With that, I'd also like documentation to feature an actual API reference, and not just guides. I hope that will help 🍉 users a lot.

But with many other maintenance responsibilities on my mind, I'd like help from the community with this. Can you help?

[KrisLau]

I can help but would probably just need some direction since I've never done this before!

Would be nice if there were more comprehensive tutorials & examples that way there'll probably be less issues opened where people ask how to do things (myself included haha). A couple things that I have found myself struggling / unable to really figure out personally would be:

• sync (steep learning curve and ran into a lot of roadblocks with implementing but might be due to lack of experience on my end)
• writer methods (nothing seemed to happen)
• cascade deletions on related tables without having to manually do so

A troubleshooting page of common problems (like #615) and a FAQ (dealing with the sync when offline, possibility of multiple relations to the same table, expo related questions, etc) would be useful as well. Also, there's someone with a PR open that is trying to add info to the observables section: #1447 which might be good as well

I'll try to put together an example project that does the full front and backend sync if I can get some free time haha. It would be nice if people could submit their own example projects too and that way there could be a couple different kinds of examples (simple & complex)

Also the demo is down: #1415 (comment)

---

Some other things I noticed were that the migrations page is under the Advanced section but says:

Without migrations, if a user of your app upgrades from one version to another, their local database will be cleared at launch, and they will lose all their data.
⚠️ Always use migrations!

If it is essential, I think it should be moved up closer to setup. My idea for sections with the current information would be something like:

• About (1.1)
  • All the sections could probably be split into separate pages for readability and easier navigation
• Setup (2.1 - 2.4 + 3.1)
• Usage (2.5 -2.9)
• Sync (its own section)
• Troubleshooting
• FAQ
• The rest of the current sections seem good as is (maybe the LokiJS & web implementation should get their own section but I don't use it so I'm not quite sure)

Let me know what you think!

---

Also, not sure if there are any other maintainers (with privileges to merge in PRs & close issues) on the repo? As far as I could tell, it's just you? Not sure if this is an option for 🍉 since it's a Nozbe repo but having more maintainers would probably help. I could probably put in a PR at https://github.com/pickhardt/maintainers-wanted if you were looking for active maintainers or just pin an issue to recruit some.

[ErickLuizA]

I want to help too, do you have anything in mind related to how it should be structured in the repo?

The current setup has the docs-master/ with the .md files and the generated docs/ folder.

Can it be changed to something like the structure found in the react-native-navigation repo, it features the API reference you mentioned or even react-native-website

Both of these examples also have versioning, is that something useful here?

[radex]

@ErickLuizA Yes, I'd like to change the structure a bit, it seems to confuse a lot of people that docs-master/ is the current version of docs that matches code on master, while docs/ matches the latest published version.

Regarding versioning, it's a nice to have, but not super important to me. I think we can start with a simple docusaurus setup, then add API reference, and then maybe think about how to ship versioned docs.

[radex]

We have this! @ErickLuizA thank you for your contribution.

The new website will be shipped alongside 0.26.0 release, for now you can view it locally like so:

cd docs-website
yarn
cd ..
yarn docs:dev  # opens in browser

[radex]

@KrisLau Your help would be definitely appreciated.

One thing you could start with if you're unsure about drafting new articles is just cleaning up the existing docs:

• Splitting large guide articles into smaller ones
• Throughout the docs, adding types to examples would be helpful. Things have changed since 2018, and I think we can now assume that most people use TypeScript/Flow, and whoever doesn't can just ignore them
• Changing navigation to be closer to your suggestion seems like a good idea

[KrisLau]

@radex Will do, I'll try to get to it as soon as I get some free time!

[radex]

About the generate docs from source code, there are some solutions, I tested the jsdoc-to-mdx, it appears to work, although I kind of just put some text and see if it outputs something, if you wanna check it out, it's in this branch, btw, for some reason, to work I need to put the comment in the .js and d.ts to work 🤔

There is this gist from the maintainer of docusaurus, but I was not able to make it run, there is also facebook/docusaurus#3413, but it's for typescript.

@ErickLuizA Can you help out with that? In general, JSDoc or something similar to annotate symbols with text seems good. JSDoc has the advantage that is has been around for a very long time, so even if one breaks, there's always going to be some tool to extract it and format it somehow.

It would be great not to have to duplicate types and just take function signatures automatically, and I think I've seen somewhere one-off scripts to help with that for Flow, but Flow just isn't that popular anymore, so it might be hard to maintain. Typedoc on the other hand looks interesting (though I don't really like how it formats the output), but I'm not sure it's a good idea to keep the main in-code documentation not in the main code but in the d.ts files.

So I think it would be great to start with a working demo of jsdoc-to-mdx, and then iterate from there

[radex]

I added some JSDoc comments to Database, Collection, etc. cc @ErickLuizA

[radex]

Also to Model, Schema, sync

[ErickLuizA]

I have not been able to open a PR with the API Reference because I didn't find a way to make jsdoc-to-mdx work properly
I don't know why, but it has some problems with flow or the .d.ts files or both.

I will try to work on another solution, maybe with jsdoc-to-markdown, it does not work out of the box with docusaurus but it's more popular, I will see if it can work.

[lucaswitch]

I will help.

[radex]

@lucaswitch Much appreciated, do you need guidance as for where to start?

[radex]

I added JSDoc to Query class as well

[KrisLau]

@radex Restructured and split up long sections here: #1535. Let me know what you think and sorry it took so long to get to it!

[radex]

@KrisLau Nice, appreciated. A few nitpicks and the README, and we'll get that merged.

[adblanc]

Hi, would love to help if still possible!

I don't know if that's the appropriate place to say this but I just tried the lib for the first time and I must say that getting a new app to work correctly with 🍉 following the documentation was a pain.
Maybe that's just me but I really struggled to find informations about DatabaseProvider, withDatabase and even the examples in the repo didn't help.

Anyway, let me know if I can contribute!

[radex]

@adblanc You can!

[lucaswitch]

@radex I was busy, is there any new docs job left to do?

[radex]

@lucaswitch Some suggestions:

• Add TypeScript types to examples in the docs
• Add docs to whatever you feel like is missing/confusing currently
• Help develop API docs by looking into JSDoc to mdx converter that @ErickLuizA started work on Help us migrate & improve 🍉 documentation #1481 (comment)
• Help develop API docs by filling in missing comments above classes and methods throughout the codebase. You can look at Database, Model, Query to see some of the work I've already done. But other things, such as explaining constructor options to SQLiteAdapter/LokiJSAdapter, decorators, Sync are not yet documented in this way.

[lucaswitch]

I'm starting on the task "Add TypeScript types to examples in the docs" not quite done yet.

[Wanderson77]

@radex
Hello everyone, I'm studying React Native and Watermelon and would also like to help with project documentation. Do you have any tips on where to start?