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

Restructure documentation #3246

Closed
wants to merge 17 commits into from
Closed

Restructure documentation #3246

wants to merge 17 commits into from

Conversation

dickermoshe
Copy link
Collaborator

@dickermoshe dickermoshe commented Sep 27, 2024

@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
Copy link
Collaborator Author

dickermoshe commented Sep 27, 2024

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

@simolus3 simolus3 changed the title rewrite Restructure documentation Sep 27, 2024
@simolus3
Copy link
Owner

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

@dickermoshe
Copy link
Collaborator Author

We could try this

Copy link

github-actions bot commented Sep 29, 2024

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

@github-actions github-actions bot temporarily deployed to pull request September 29, 2024 15:08 Inactive
@dickermoshe
Copy link
Collaborator Author

Seems docker is working again

@github-actions github-actions bot temporarily deployed to pull request September 29, 2024 15:15 Inactive
@github-actions github-actions bot temporarily deployed to commit September 29, 2024 15:15 Inactive
Copy link
Owner

@simolus3 simolus3 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


## Overview

In Drift, your schema is represented as a table. Each column in the table represents a field in your data class.
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 👍

docs/docs/schema.md Outdated Show resolved Hide resolved
Comment on lines 34 to 37
After defining the schema, add the table to the database.

{{ load_snippet('superhero_database','lib/snippets/schema.dart.excerpt.json') }}

Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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).

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

dart run build_runner build
```

<h4>Congratulations! 🎉🎉</h4>
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

You've successfully defined the schema for your database.
You can now use the generated code to interact with your database.

{{ load_snippet('superhero_query','lib/snippets/schema.dart.excerpt.json') }}
Copy link
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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

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

simolus3 commented Oct 1, 2024

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

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

@dickermoshe

This comment was marked as off-topic.

@github-actions github-actions bot temporarily deployed to commit October 2, 2024 04:04 Inactive
@github-actions github-actions bot temporarily deployed to pull request October 2, 2024 04:04 Inactive
@github-actions github-actions bot temporarily deployed to commit October 7, 2024 02:07 Inactive
@github-actions github-actions bot temporarily deployed to pull request October 7, 2024 02:07 Inactive
@dickermoshe
Copy link
Collaborator Author

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

@simolus3 simolus3 deleted the docs-rewrite branch October 15, 2024 07:59
@dickermoshe
Copy link
Collaborator Author

dickermoshe commented Oct 15, 2024

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

@simolus3
Copy link
Owner

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.

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

Successfully merging this pull request may close these issues.

2 participants