withastro
Proposal to reorder Astro DB documentation sections for improved flow
📚 Subject area/topic
Integration Astro DB
📋 Page(s) affected (or suggested, for new content)
https://docs.astro.build/en/guides/astro-db
📋 Description of content that is out-of-date or incorrect
When following the documentation for Astro DB from top to bottom, users may/will encounter an error due to the placement of certain sections. Specifically, the section Table References which details how to create a relation between database tables is positioned before the sections covering basic querying and inserting operations. This can lead to confusion and difficulty in following the tutorial seamlessly.
Following the existing guide sequentially:
- The user creates the Comment table.
- The guide then introduces "Table References", which details creating relationships between the Comment and Author table. The user is very likely to refactor step 1 to match this new table structure.
- However the code sample in the Select section shows querying from the "old" version of the table Comment that no longer exists at point. The field "author" is now replaced with the authors id reference.
- When trying to insert a new row the user encounters the error:
SQLITE_CONSTRAINT_NOTNULL: NOT NULL constraint failed: Comment.authorId
Proposal: I suggest reordering the documentation sections to improve the flow and make it easier for users to follow along without encountering errors. Specifically, I propose moving the section on creating table references down to the bottom of the documentation, right next to the section on relationships.
By doing so, users will first learn the basics of querying and inserting rows into a simple table, which provides a foundational understanding before delving into "more advanced" topics like table relationships. This approach might reduce the likelihood of errors or confusion leading to a more logical and intuitive progression of learning experience and result in a smoother onboarding process.
I can provide a PR, if you wish.
🖥️ Reproduction in StackBlitz (if reporting incorrect content or code samples)
No response
