sveltejs
Sveltekit documentation is not beginner friendly at all.
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
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?
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.
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?
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.
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
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?
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?
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.
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.
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 https://github.com/sveltejs/kit/issues/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.
Look at me here。I have only one suggestion, can the document support Chinese?
Look at me here。I have only one suggestion, can the document support Chinese?
Consider making a separate issue for this.
IMHO the problem with documentation comes exactly with breaking changes before 1.0 release. Before this, the net are plenty of tutorials, videos, and examples for SK, Now only a few of them are updated to the new SK API. Also SK documentation is not "the panacea". Many examples and concrete use cases are missing.
Many relatively experienced developers are never quite sure if what we are doing is correct or not, even if it works. I think the documentation is missing many examples of what NOT to do.
Before I say anything else: I'm not speaking for the contributors here. I am not one and should therefor not be considered one. Just saying this because my response may be taken as an official one due to its length. Let it be clear I am just a user like you guys.
That said...
I feel like the majority of you guys jumped into deep water and are now being grumpy because you had trouble swimming the first time.
At the same time I think that you guys are expecting the wrong things from the documentation.
When you open the manual of a saw blade, you should not expect it to teach you how to build a lodge. Just like when you lookup tutorials on how to use that sawblade, you should not expect a tutorial on how to build a tiny home with it.
Maybe you get lucky sometimes and find someone that made a specific tutorial for your use case, but it should never be expected unless that is explicitly advertised on the sawblades product page.
What you should expect from that sawblade manual however, in my opinion, is that it shows you how you can use the sawblade to cut different types of materials. It should tell you about its limitations and primary use cases.
When you translate this analogy to SvelteKit, you'll see that SvelteKit's documentation does this very well already. It is well documented how to make SPAs, MPA's, Deploy to different enviorments using the adapters, handle formdata, there is the appendix, etcetera.
If you want to make the argument that there should be more specific niche content about "how to build X with SvelteKit", I happily agree. I even want to go as far as recommending Rich Harris to spend time writing a paid course in his spare time, and launch it alongside the new official free SvelteKit tutorial. The reasoning behind that opinion of mine is my believe that every paid thing motives people to make free alternatives. In this case it would indirectly lead to more free tutorials, more free examples of high quality... which I think is what we all want?... and also from a business perspective would generate some additional credibility and money for Svelte in the long run.... just a train of thought.
Anyways, I think that this issue should be closed as this isn't really a issue anymore. It seems to be that it has morphed into an open discussion, which belongs on the discussions tab on this repository. You can blame that on me, shit happens ¯\(ツ)/¯
Just my two cents here, but I completely agree with @UltraCakeBakery. The SvelteKit docs have gotten quite great. I've been using SvelteKit both professionally and for hobby projects and it has been mostly great. It's still in its infancy and you can't expect the resources to be to the same caliber as with React or Next for example. Although, it has gotten quite good, to the point that you don't need to be in the GitHub issues to see if an edge case that you have is actually a bug or expected behaviour, so I thank the contributors for that. That being said, especially with open source projects that are maintained by people who love those projects, there are two solutions to your problem:
- You find an edge case that's not documented, instead of complaining, raise a PR trying to document it and align with the maintainers to make it as good as you can and boom, you have both added that edge case in the documentation and helped other people not to be in your position.
- Use a different tool. If Astro's documentation is covering all your use cases, great! Use Astro.
I honestly don't understand why when you are provided with a free tool, there's the expectation for everything you need to know, to be spelled out in front of you. Mastering a tool takes time and effort both from the creators and users. If you're not willing to invest the time to understand how something works and help out your fellow users with an issue or documentation that may be missing, maybe you shouldn't be using said tool.
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.
{irony-mode} Yeah, that's it. Basically if you are a beginner in SvelteKit, you don't deserve SvelteKit. You must learn SvelteKit to understand the docs. Go, learn swimming and then maybe you'll be granted to use this free and philanthropic tool those masters gifted us and you, miserable worm, dared to criticize. {/irony mode}
Some community members disdaining and bullying new users who are trying to get into Svelte and have some troubles with the docs, and the author publishing reviews to the docs. That's educational. Let's hope this community does not get rotten by those individuals like they did on the Ionic forums.