Add Data Fetching Guide

[amirhhashemi]

• I have read the Contribution guide
• This PR references an issue (except for typos, broken links, or other minor problems)

Description

The idea of the Guides section is to provide a resource for developers who don't read Solid.js and Solid Router docs before learning SolidStart, such as React developers who may think of SolidStart as what Next.js is for React and start learning Solid.js from SolidStart. However, I think a Guides section can be useful to a lot of people regardless of whether they come from React.

The goal is to get those users (or anyone really) up and running with SolidStart as quickly as possible, while also guiding them to read more relevant docs if they want to learn more.

This PR adds a Data Fetching page under the Guides section that covers basic data fetching patterns while providing links to relevant documentation for those who want to learn more.

See #861 for more context.

Related issues & labels

#914 #861

[stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[netlify]

✅ Deploy Preview for solid-docs ready!

Name	Link
🔨 Latest commit	d2821c5
🔍 Latest deploy log	https://app.netlify.com/sites/solid-docs/deploys/679514cd628e08000896c550
😎 Deploy Preview	https://deploy-preview-991--solid-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[LadyBluenotes]

Hi @amirhhashemi,

First of all, thank you for taking the time to work on this, I appreciate the time you're taking out of your day to improve our documentation.

It might be useful to take a look at the diataxis documentation on how guides should be written. We use this as a reference for writing our docs, and i feel like it could be helpful to consider for this!

If you'd like some more directed feedback, however, please let me know

[amirhhashemi]

Hi @LadyBluenotes

Thank you for the feedback. I made some changes based on the diataxis guide:

1. I removed all explanations that are more suited for a tutorial page and only relied on links to provide more info.
2. I tried to make each section more action-oriented. Now, the titles start with "How to" and the minimal description of each section starts with "To do".
3. I reordered the sections to create a better flow.

I'm not sure about:

1. Whether I should keep the examples self-contained. I think it's a good thing because readers can pick up each section and copy its example without needing to read the previous sections.
2. Whether the section about Tanstack Query belongs on this page. Maybe it's more suited for a tutorial page or the "build your application" section.

[LadyBluenotes]

Hi @LadyBluenotes

Thank you for the feedback. I made some changes based on the diataxis guide:

1. I removed all explanations that are more suited for a tutorial page and only relied on links to provide more info.

2. I tried to make each section more action-oriented. Now, the titles start with "How to" and the minimal description of each section starts with "To do".

3. I reordered the sections to create a better flow.

I'm not sure about:

1. Whether I should keep the examples self-contained. I think it's a good thing because readers can pick up each section and copy its example without needing to read the previous sections.

2. Whether the section about Tanstack Query belongs on this page. Maybe it's more suited for a tutorial page or the "build your application" section.

Thank you for adding some changes! One comment I do want to make, is that I think adding back some (basic) explanations can be helpful. Doesn't have to explain anything but the process, such as this:

To show users that data is loading, you can display a loading UI while they wait. You can achieve this by wrapping your component in Solid's <Suspense> component and using the fallback prop to specify what should be shown during the loading process. Here's how:

1. Import the component from SolidJS.
2. Wrap your component with and define a fallback UI to display while waiting for the data to load.

This way it follows we have the code snippet explained a bit in case users need some kind of explanation (but not giving too much background about the topic itself, which is more appropriate for other sections in the docs). This is a pretty rough example but we can either have it as a quick list (if you feel it's necessary) or just a simple explanation of how things are set up in the snippet.

I do agree that, to an extent, having each section self-contained is important. We don't want them so far removed that they could be considered separate entirely, but enough that there is some relationship (even if marginally).

As for the Tanstack Query section, I do agree that it would probably be better suited for a tutorial than in here. That being said, a callout could probably replace the section saying something as simple as what you wrote for the first sentence:

Tanstack Query can be used for more advanced features such as automatic background re-fetching or infinite queries.

Do you have any questions/ comments about what I mentioned?

[amirhhashemi]

Thank you for the feedback.

I've added basic explanations for each section. However, I have some concerns:

1. Some explanations may be redundant and could be streamlined
2. I'm particularly uncertain about the createResource section - it's challenging to explain without diving too deep into its internal workings

I would appreciate your feedback on these points. Please feel free to edit the document directly if needed.

Regarding Tanstack Query: I've removed the dedicated section and added a brief note about it at the end of the createResource section instead.

[amirhhashemi]

I'm wondering whether we should remove the "how to" from section titles:

• How to handle errors -> Handling errors
• How to preload data -> Preloading data
  etc

The way this guide is written, it's obvious we are only talking about how to do stuff, and not why and when. I think we can remove it. What do you think?

[LadyBluenotes]

@amirhhashemi Thank you for adding the explanations! I'll try and get to reviewing them this weekend (and seeing how we can approach the createResource section) but I wanted to say I think it's a great Idea to update the titles to remove the how to parts!

[LadyBluenotes]

Let me know how you feel about these changes, but I feel like you did a great job explaining each code snippet briefly.

[atilafassina]

Great work!!

I just had those 2 small comments / nitpicks