New and better documentation for kit

[theetherGit]

Why we need a new documentation

• After breaking changes we all got confused with all the information and not that explanation.
• Better representation of docs is needed now we are about to be on v1 of kit.
• learn.svelte.dev is good but we don't wanna go there always.

What we can do with new docs (My point of view)

• I love the way tailwind have there docs. (eg: representative, easy to grab things)
• We can do explanations and some examples in docs and then can link to learn.svelte.dev tutorial which will make things understandable with playground.
• Proper guide from start to end, one step at a time. eg. project setup, template explanation to the advanced topics e.g advanced layouts etc.

Additional things we can do

• Add some more real world examples eg. Authentication using cookies, prisma integration, some web socket examples.

There are many more things we can do with docs and it might me little bit chaotic idea. But what i think is if we have a better docs and example explanations beginners like me can get to know more. For now there are not so much tutorials and blogs on kit online.

[aradalvand]

I generally agree with the point that the SvelteKit documentation certainly has room for improvement. In a lot of cases, it's a little too concise and not sufficiently comprehensive or elaborate, which has been understandable so far because we haven't yet reached 1.0 and so it's not worth it trying to elaborately explain things when we might have breaking changes or whatnot at any time. That said, I think now is a good time to start improving the docs since things have gotten pretty stable at this point.

[theetherGit]

Yeah @aradalvand you have a point but yesterday @Rich-Harris announced kit is now in release candidate phase in svelte summit dated: 9th Sept 2022 which means there will be no intentional breaking changes in kit. So i thought it's time to move things for docs too.

[aradalvand]

@theetherGit Yeah I definitely agree, I did point that out in my comment:

That said, I think now is a good time to start improving the docs since things have gotten pretty stable at this point.

[theetherGit]

😅

[david-plugge]

Most important feature we need is darkmode 😎

[chidam333]

Yeah man !!! We need new docs , i don't even know what is up with 2 line code snippets where it goes like
interface this stuff stuff stuff go brrr
It took me so much time to understand even what a basic interface Cookie does . Docs is bad now i guess , or i can't read it the right way

[theetherGit]

I don't know if it's gonna help you but for now you can go through some of my articles i have been writing
Sveltekit Changes Article series

[dummdidumm]

Those who have upvoted: Which things specifically do you want to see improved? Please be as detailed as possible, for example "the docs about form actions are confusing because X" or "I miss more information about feature Y, right now there's only Z which is not enough".

[chidam333]

Things like pagedata or even as simple as cookies could be made easier. Cookies in documentation looks overly complicated with comments filled code snippet. When i ctrl k about pagedata or many other stuff it shows a 2 liner.

[janzheng]

There are lots of situations where I try to do action A, but how I do it depends on the situation. For example, getting URL params is harder than it should be. Yes, you can do "URLSearchParams" but not on the server-side if the site is pre-generated. I think what would help is a few "recipes" for these, e.g. "how to get URLSearchParams on hooks that run both on server and client", "how to get URLSearchParams only on server", "how to get URLSearchParams on generated pages; e.g. you can't, so you use [params] instead and here's how"

The docs are kind of complicated to the point that it might scare away new users. As someone who's been using SvelteKit since the Sapper days, I kind of have a somewhat good grasp of how every piece "fits together" but that gets lost for newcomers. I can see this be extremely frustrating for someone new trying to figure out how to "get stuff done quickly" on SvelteKit, which is what drew me to Sapper in the first place.

I think some of the original "intuitiveness" now lost in the added complexity of the new SvelteKit system, so the documentation has to make up for it by having a ton more examples and addressing use cases, in addition to documenting the system itself.

[mtaron]

It would be nice if common use cases like "how to integrate with Passport.js" or a worked example of adding any middleware to polka were included in the docs.

[danawoodman]

I know as we approach V1 docs will become more a priority, which I think is great since the approach till now has been solidifying the API.

I think in general having lots more examples of how to solve common problems would be the most impactful improvement we could make.

I spend a lot of time helping people on discord and almost all the questions are in a handful of common categories that the docs should address (auth being a huge one, for example).

I get we don't want to be prescriptive, but a section on solutions would be invaluable.

I've resorted to writing blog posts on a lot of these, but ultimately it just means people have to rely on external sources instead of the docs.

I would say that the Discord/Discussion sections should be combed for questions and a list sorted by frequency made as a jumping off point. Then for each general topic, create a "recipes" section for each, listing considerations, gotchas and alternate approaches. This way people who are fielding questions have a canonical place to send people for their questions, versus answering in haphazard ways as we are doing now.

One other topic which I know has been discussed but really needs to be solved is showing all examples in TypeScript. People constantly ask how to use TS with SvelteKit as JSDoc syntax isn't clear for some people on how to adapt to TS and it is not nearly as popular as plain TS. I know it's the preference of the Kit team (or maybe just Rich?), but that isn't the general consensus from what I've seen and causes regular confusion.

[ivodolenc]

I'm still new to Svelte/SvelteKit, I've been playing with it for about two weeks and I really like the development experience. It is simple and practical, especially for SEO and static data generation.

I'm also thinking about moving the projects to SvelteKit when you release the first production version.

But sometimes it can be difficult to find the right information in the documents and it would be great if the documents can be improved. I'm interested in contributing, maybe for now in design or something since I'm new to Svelte.

I like the Discord chat (new support channel for easier search) and this discussion, it's really helpful.

Some suggestions I like to see in the docs when learning a new stack:

• The main layout of docs divided into 3 sections:
  • Left - Main navigation
  • Center - Content
  • Right - Second navigation (current location on website), sponsors, plugins, links, etc...
• Great anchor and scrolltoview system when there is external linking
• Short and clear calls to action on front pages
• Good grouping of main topics like getting started, setup, project structure, API, basics, best practices, examples, etc...
• Good explanation for client and server environment
• Good information for global data, how to import external libraries, advanced configurations, etc...
• All migration guides have been added to a separate page with all the information in one place - before and after examples
• Dark mode
• All code examples must have title/source information and where the example should go/paste (in comments or above the example)

// +page.js/+page.server.js/+server.js -> this can be confusing :)

export const prerender = true

Not required, but good to have, especially for beginners:

• more examples for community contributors (plugin authors)
• more video tutorials (levelup tuts, net ninja crash course and vercel beginner sveltekit course on youtube are great)

Some examples of good docs that are easy to follow:

• Vercel, Next, Tailwind, Vite, Vue, Strapi, Nuxt, Framer developers, etc...

[Gravy59]

React Beta Docs have completely redefined how docs should be made, might be good to take some leaves from their book too