Sveltekit documentation is not beginner friendly at all.

[ciprian-marius]

Describe the problem

There's a lot of hype around Svelte at the moment and i followed the hype and got myself here. After 2 weeks I can say that I really like Svelte but inevitable i got introduced to Sveltekit as well and i end up with a very bitter taste in my month. The high level, dry, incomplete or even lack of documentation is the reason. I really want Svelte to succeed but I dont feel very confident if beginners end up being mentally abused by the sveltekit documentation or lack of it.

Describe the proposed solution

I believe is the responsibility of sveltekit developers and not the community to document properly the core concepts of sveltekit.

Alternatives considered

No response

Importance

i cannot use SvelteKit without it

Additional Information

No response

[frederikhors]

I've been using Kit since there wasn't even a documentation and the one there is now is WONDERFUL!

What EXACTLY is it that you don't understand?

[ciprian-marius]

Well im sure if I was using kit since the times it didnt even had a documentation i would think the current one is "WONDERFUL" as well. I'm a beginner with js frameworks and the current documentation does a very poor job at explaining how core concepts work in different modes (SPA, SSG, SSR) for example. It also doesnt even mention how some svelte concepts work in kit, like stores. On top of everything there's a lot of edge cases that could be easily solved with a few paragraphs of documentation. This would solve a lot frustration and time.

You can give astro documentation a read. While its not perfect, i find it like 3 times better and the reason i switched from kit to astro.

[dummdidumm]

Could you be more specific about the edge cases? What where those?

The meaning of the different modes is explained here: https://kit.svelte.dev/docs/glossary . If you saw that, what did you find was missing from it? If you didn't saw that, why? Was it not discoverable enough? Or is this more related to what these modes mean for SvelteKit and what do look out for when using one of them?

What do you mean about stores in relation to SvelteKit? They work the same, there's nothing specific to it. What exactly was the problem here?

Did you know about the SvelteKit tutorial? https://learn.svelte.dev/tutorial/introducing-sveltekit if yes, what did you find was missing to answer some of your questions?

[Smirow]

I also find the current kit and Svelte documentation pretty good (and I recently learned Svelte and kit on those). The tutorial is brillant. I think I never grasped the ins and outs of a great piece of code that quickly.

[ciprian-marius]

I lost all interest in sveltekit but i will do a final good gesture and point out a few things.

• Take a look how astro documented routes and fetch and how they work in different modes.
• How astro documented stores and what happens for example if you try to use a store on the server side (im a noob, i wasted hours researching this). They do a better job at documenting svelte stores than sveltekit.
• some core concepts are not really clear such as when things happen on the server or the client and why and when load happens on both
• The glossary is good but doesnt explain how sveltekit core concepts work in different modes. Like for example what are the sveltekit api limitations when you work in SPA mode. Im a beginner i dont know this. I'm tempted to believe there are none, otherwise there would be some warnings, no?!
• You can use sveltekit in SSR with node as an adapter. What happens if you try to use node builtins. also lost so much time researching this. Astro has it all covered.
• how to deploy on apache and ngxing, the most popular servers. more than 70% of websites are hosted on these.
• there's more, again, use astro as inspiration.

Final thought, i find it inexcusable that the most loved framework in the world (according to marketing) doesnt even have an API reference. I will not even mention anything about a decent error feedback system. I've been doing php and python backend using loads of frameworks some were well established some were very new but i never remember to stumble upon one that doesnt have an API reference.

Anyway, i've seen how sveltekit developers replied in other cases when someone complained about the documentation so I will stop here with my feedback.

Wish you all good luck

[teemingc]

https://kit.svelte.dev/docs/modules

Is this considered an API reference? I have been using this section for most of time with SvelteKit. Would renaming it make it more recognisable as such?

[UltraCakeBakery]

I lost all interest in sveltekit but i will do a final good gesture and point out a few things.

• Take a look how astro documented routes and fetch and how they work in different modes.
• How astro documented stores and what happens for example if you try to use a store on the server side (im a noob, i wasted hours researching this). They do a better job at documenting svelte stores than sveltekit.
• some core concepts are not really clear such as when things happen on the server or the client and why and when load happens on both
• The glossary is good but doesnt explain how sveltekit core concepts work in different modes. Like for example what are the sveltekit api limitations when you work in SPA mode. Im a beginner i dont know this. I'm tempted to believe there are none, otherwise there would be some warnings, no?!
• You can use sveltekit in SSR with node as an adapter. What happens if you try to use node builtins. also lost so much time researching this. Astro has it all covered.
• how to deploy on apache and ngxing, the most popular servers. more than 70% of websites are hosted on these.
• there's more, again, use astro as inspiration.

Final thought, i find it inexcusable that the most loved framework in the world (according to marketing) doesnt even have an API reference. I will not even mention anything about a decent error feedback system. I've been doing php and python backend using loads of frameworks some were well established some were very new but i never remember to stumble upon one that doesnt have an API reference.

Anyway, i've seen how sveltekit developers replied in other cases when someone complained about the documentation so I will stop here with my feedback.

Wish you all good luck

You need to learn how to blame yourself for everything that happens to you or you do not understand, instead of the people and their manuals around you. You keep pointing at things, saying they are better, without elaborating why they are better or giving any direct links to examples.

Take a look how astro documented routes and fetch and how they work in different modes.

I'm looking at it. What should I be paying attention to exactly? What do you find better about this documentation?

How astro documented stores and what happens for example if you try to use a store on the server side (im a noob, i wasted hours researching this). They do a better job at documenting svelte stores than sveltekit.

What is it exactly that they do better? What confusion inevitably lead you to now confess to us that you are a noob (your words, not mine) that wasted hours researching.... what exactly?

some core concepts are not really clear such as when things happen on the server or the client and why and when load happens on both

You read both the astro documentation and SvelteKit documentation so well that you think you are in the position to claim that it is not beginner friendly at all, yet you didn't check the very first message in the documentation that points to the tutorial where this concept is explained later on.

That tutorial is relatively new, so I will assume you didn't know about this before making this post... but when you check the routing section of the docs for example, which has been around for some time now, it clearly is stated there what runs on the server side and what does not.

The glossary is good but doesnt explain how sveltekit core concepts work in different modes. Like for example what are the sveltekit api limitations when you work in SPA mode. Im a beginner i dont know this. I'm tempted to believe there are none, otherwise there would be some warnings, no?!

What makes the glossary good? What core concepts? What do you mean with "sveltekit api limitations"? What are you even trying to say here? That there are arbitrary or fundamental limitations you ran into? If so, did you make a separate issue about that you can link to in the additional info section of your original issue? I'm sure the maintainers are open to discuss new features or changes if they benefit users.

You can use sveltekit in SSR with node as an adapter. What happens if you try to use node builtins. also lost so much time researching this. Astro has it all covered.

What happens, or does not happen? We now have to guess what you are talking about. You can't use them? Did you try to run nodejs stuff in the browsers runtime? What does Astro have covered EXACTLY that svelte kit does not?

how to deploy on apache and ngxing, the most popular servers. more than 70% of websites are hosted on thes

Why should this be covered? You got a source for that outdated claim about 70% of websites using nginx/apache?

there's more, again, use astro as inspiration.

Examples? No more than three links or comparisons would've been more than plenty.

I will not even mention anything about a decent error feedback system

Awwh man, really? You are not going to mention how Astro does this better too? Thats a bummer dude....

Jokes aside, what do you find bad about the current "error feedback system"? What do you even mean with "error feedback system"? Are you talking about the messages generated by vite? The console logs when you make a typo? What exactly is not "decent"? Do you want chat GTP to automatically give you suggestions on how you can fix your code or something like that?

Anyway, i've seen how sveltekit developers replied in other cases when someone complained about the documentation so I will stop here with my feedback.

Can you link to any examples?

[NormandoHall]

Svelte is very good documented with examples and touching all the potencial things a beginner can do. For example, in each case "Do this, not this!".

Developers are with the brain inside the code. The best thing they can do is to sit a beginner on front of documentation, and asked what items no understand, and take note for improve. Documentation is important, and I see this is an issue with kit.

[frck006]

Hi

Can you explain in SSR mode, universal, "load" function is executed twice, in the server and browser. Why is better or necessary ?
Like that, it seems that the program will take 2x time, no ?
If the load function takes 10s, we'll have 10s (server) +10s (browser) ?

Regards.

[henrikvilhelmberglund]

I can agree with Sveltekit docs not being beginner friendly all of the time. Generally I have had better luck just googling to find stackoverflow questions or github issues than finding the answers in the documentation. Maybe it's because I don't have any experience with other frameworks/metaframeworks but I feel like there's a jump between vanilla JS and Sveltekit sometimes.

For example today I wanted to fetch() fakestoreapi and use some buttons to change the query string (for example ?sort=desc or whatever) and clicking a button would run fetch() again with the new query string. Maybe this is too obvious for it to have a place in the documentation but I can't really see how I would accomplish this just by reading the docs.

https://kit.svelte.dev/docs/load#using-url-data had some info but it didn't really help since my problem was actually running the load function again with the new query string. After googling I found a stackoverflow question with basically what I was wondering which had questionable answers like modifying the $page store, but in a comment there was a link to an issue #2785 where someone used goto for something like that. Eventually I got it working but the documentation didn't help that much.

Even now I don't know if goto is what should be used to do that or if there's a better way.

[mydracula]

Look at me here。I have only one suggestion, can the document support Chinese?