Restructure documentation

[dickermoshe]

@simolus3
Check these as we go along with this
I'll be adding checkboxes once more docs are completed.

Schema

• I simplified the datetime stuff. I will put the detailed explanation on datetime migrations on another page
• Indexes will have their own page
• Relations will have their own page
• Row Classes will have their own page
• Added more examples
• Added a overview to the page
• put some stuff in advance
• Made clientDefault the recommended way to to defaults

@simolus3 -> for you to check when satisfied:

• Schema.md looks great !!!

[dickermoshe]

@simolus3 Seems docker is failing. Don't know if this is a github, docker or Drift issue.

[simolus3]

Maybe Docker Hub is rate-limiting unauthenticated GitHub actions? If the problem persists we might have to use another registry for the dependencies.

[dickermoshe]

We could try this

[github-actions]

🚀 Deployed on https://deploy-preview-3246--moor.netlify.app

[dickermoshe]

Seems docker is working again

[simolus3]

Some comments on the schema page. It reads really nicely, I think my biggest question is what role this page should have (at the moment, part of it read like an in-depth reference, parts read like a getting started guide for people who have never used drift or build runner). The docs need to be good for both, but I think it will be hard to reconcile this on a single page.

[simolus3]

Pedantically speaking, the schema is actually represented by multiple tables (and views, indices, ...) 🤓

Perhaps we can phrase this introduction as a "Drift is a library for relational databases, meaning that your data is structured into data with predefined columns" or something?
The rest of the introduction is nice 👍

[simolus3]

I guess databases will also have their own page introducing them? We should also think about a setup page that explains everything step by step (which could link to the dedicated pages for support).

[dickermoshe]

Yup, there will be a getting started guide and another page devoted to the database itself.
Giving each page it's own overview gives users a broader sense of what's going on

[simolus3]

This reads like part of a guided setup tour, but I'm not sure if this page is supposed to take that role or if it should explain tables in more detail as a reference page?

I guess it will be easier to move content around once we have the basics in place, but I'd prefer to keep the distinction between guides showing everything step by step and these in-depth reference pages that (I suppose) will mostly be used to quickly look something up.

[dickermoshe]

I'll rewrite the later parts of the page to be more "reference-like", but an friendly overview gives users a sense of security

[simolus3]

I wonder if we should have tabs here to show how to do this with manager and with the regular query builder (happy to write half of the snippets in that case :D)

[dickermoshe]

I plan on breaking up the query docs into 3 parts

Manager API
Core API
SQL APi

The Manager API is the simplest, so I want that to be the 1st thing users see.
In the query docs that I'm in middle of writing I reference the Core API docs for more complex operations.

[dickermoshe]

Some comments on the schema page. It reads really nicely, I think my biggest question is what role this page should have (at the moment, part of it read like an in-depth reference, parts read like a getting started guide for people who have never used drift or build runner). The docs need to be good for both, but I think it will be hard to reconcile this on a single page.

The more I think about this, the more I'm convinced you're right.
I'm going to put this on hold until I have a better plan of action.

[dickermoshe]

The focus of this restructuring is mainly for the 5 or 6 pages that users will go to when they discover drift.
There is some legacy stuff which will confuse new users (sqlflite) which should be explained better.

Overall the docs are pretty ok. I'm focusing mostly on PR, while you're focusing on maintaining a high quality package. Geez, get better priorities man😉

[simolus3]

The focus of this restructuring is mainly for the 5 or 6 pages that users will go to when they discover drift.

Maybe we could duplicate some of the information and restructure contents into a "reference" section (basically what we have at the moment) and a guide section that has the setup and these friendlier/high-level introductions to common things like tables, references and row classes. Then at the top of each page we'd put a box saying "This page gives an introduction to tables for users exploring drift. For a complete reference see, link1, link2, link3." (and similarly the reference pages could link to the guides).

[dickermoshe]

Instead of reinventing the wheel, I'm going to copy drizzle structure

[dickermoshe]

Closing.
We're going to do this a single page at a time until everything is nice.

[dickermoshe]

If Celest starts to take off, we're going to be overrun with new users.
Let's try to get this done quicker

[simolus3]

Let's try to get this done quicker

Agreed :+1 I've responded to your message, let me know if there's anything else I can do to help here :) I can also help with examples or writing sections once we have a good understanding on how to structure things.