I dislike the new docs

[azezsan]

I want to start by saying I really appreciate the hard work the Svelte team has put in over the past months. I truly believe Svelte is the best framework I've worked with so far, and it's awesome to see it built by this amazing community.

With all that said, I can't help but feel like the team may have missed the mark with the new docs. While I've been following Rich Harris on the redesign for a while, I never understood why the site needed a redesign. but I thought Perhaps I'm just missing the point, but after it's now done it just feels wrong... Let me explain my points:

There wasn't anything wrong with the initial approach. The Svelte site and the SvelteKit site should be separate. These are, after all, different technologies. While you can't use SvelteKit without Svelte, you could use Svelte without SvelteKit. That's why every other framework and language keeps these things separate: Ruby and Ruby on Rails, React and Next.js/Remix, Vue and Nuxt.js. Even though Svelte and SvelteKit are maintained by the same team, they're still two distinct technologies.
What was wrong with the old docs? Perhaps merging the two sites is understandable, but the style and font of the new docs feel like a downgrade to me. As far as I know, nobody was complaining about the docs looking ugly, having hard-to-read fonts, or needing a redesign in general. It was beautiful as it was. The new change feels very opinionated and does nothing but open a door for splitting the community into two: a side that finds it cool and a side that hates it. This makes the change feel quite unnecessary.

Old: https://svelte.dev/docs/introduction
New: https://svelte-omnisite.vercel.app/docs/svelte/getting-started

I know this is not the final redesign, so I wanted to share my thoughts. Please don't take my feedback here as hate; that's not my intention at all.

[shinebayar-g]

It seems that Svelte & SvelteKit docs are still separate.

However, I agree with the font choice and overall accessibility of the new docs seems off. Very hard to read and focus. Old documentation website had subtle aesthetics which made it very easy to read.

vs

Hopefully it'll be improved 🤞

[azezsan]

I miss it already 😢

[brunnerh]

Related issue regarding fonts:

• [omnisite docs] Contrast and font - terrible for my eyesight svelte.dev#517

Personally, I think the font would be acceptable in the light theme (which is itself not acceptable), and counter-productive in the dark theme.

The merging of the the sites is helpful for many people. Often people end up not finding something because they accidentally looked in the wrong site. I also now don't need to have two tabs open at all times without any real benefit.

[azezsan]

I'm cool with merging but the new design was a step back from something that was close to perfect.

[DaanKorver]

I agree. Especially the font really hurts my eyes. As someone who has trouble reading for long periods of time, the new serif font combined with the theme colors aren't helping with that.

[mjdNjhNJ]

Merging is definitely beneficial and I don't have anything against it either. The font is nice for the landing page but definitely not for the documentation.

[pavelstianko]

I agree - I have a lot of problems reading the new docs in sans-serif. I love Svelte, but I can't concetrate on text where is serif (paragraphs) and sans-serif (inline code blocks) together. My OCD part is suffering and I need to close it after few minutes :D

[msikma]

I appreciate that the docs were refreshed for the update, but I agree with others that it's just difficult to read with the current font. It's not terrible, but it could be a lot better. Using a heavier sans serif font would make it a lot easier to read.

For now I think the safest and best option would be to just revert to the previous font, and for any changes to be done on a careful basis with feedback and testing.

[JacobGoldenArt]

I see @azezsan point, but I personally disagree. I like how svelte does it's own thing. the Serif font is quite different compared to a lot of other sites, but I'm happy that the Svelte team are not afraid to buck design trends and present themselves as they want to. I'm not sure if I agree with the idea that Serif fonts are better for readability that Harris shared in his blog post on the redesign, but it's certainly is a more unique and creative approach and certainly valid.
One way that might accommodate folks that don't like reading Serif, could be to add a toggle that toggles the font between Sans and Serif (kind of like toggling dark mode). As far a content though, The docs and the tutorial updates are excellently written, super clear and very helpful for me (as a non svelte expert). Just my two cents!

[PeshO2K]

I agree with @azezsan , it's worse in dark mode. I personally don't care about font. The lack of visual hierarchy in the dropdown menu is frustrating in dark mode. I can't quickly scan the content like before. The redesign was unnecessary

[ivands]

The font is simply harder to read.
Hard dislike for me.

[brunnerh]

Did you see the font toggle in top right?

[ivands]

I didn't, thanks for the heads up.

[ivands]

Sadly it doesn't work for titles, and labels.
Would be great if it changed all fonts.

[kvetoslavnovak]

I agree. Accessibility and inclusion have indeed decreased.
However, according to the Svelte Blog itself:
At the same time, we couldn’t bring ourselves to look the same as every other documentation site. Modern web design is stiflingly anodyne: everything is boxes, purple glowy nonsense, and the same handful of sans serif typefaces. ... We know this is a controversial choice! ... It may take some getting used to. We also recognise that there may be some legitimate readability concerns for some people...

I really don't think there's a need to be different just for the sake of being different. Svelte is already so mature that it doesn't require this. By the way, I have quite a corporate background (at one of the world's top 20 banks group), and serif fonts were abandoned a very very long time ago there, for good reason.

EDIT: And no, you will not get used to a serif font if you have reading disabilities, which affect around 20% of the population. Therefore, having a serif font as the default is a highly questionable move.

[aaronpeacock]

I would like the opportunity to provide feedback without a ton of downvotes, this isn't Reddit.
I say all of the below as an avid Svelte user since v3 (with several apps still ON V3...)

The old docs were better, IMO (strong opinion)
I find the new docs to be significantly less useful. If I may be candid here:

I dislike the new font intensely. It seriously makes me fall asleep and unable to process the text on the page.

I dislike the mixing of SvelteKit and Svelte throughout the docs, I don't WANT SvelteKit, nor am I seeking any backend solution. I don't want Svelte giving me an opinion about my backend.
I feel that they are 2 different projects and should NOT share the same site nor docs. I feel strongly about this.
I need a FRONTEND framework and that was Svelte, until now.

I dislike that the docs page is now a multiple-choice docs LANDING PAGE, with multiple confusing options and lots of text in this font I mentioned my dislike for. https://svelte.dev/docs

https://svelte.dev/docs/svelte/overview
The initial "hello world" example is reasonable enough... however, it rapidly turns into what seems like soup to me.
It's almost as if my previous years of Svelte experience mean NOTHING. A list of $stuff where previous docs gave me a sense of the architecture and API.
I'm lost here. No parallels from Svelte 3 or 4, just dropping us into "runes" .
While the actual syntax may reflect Svelte 5, the way it is presented in what are termed "reference docs" looks NOISY IMO.

First thing: I bump into this https://svelte.dev/docs/svelte/getting-started
What!?
Again, I am cajoled into considering throwing away my entire backend and just adopting SvelteKit, to DEVELOP SVELTE FRONTEND CODE!? why? Oh, it has local server!
News Flash: not everyone is writing an SPA. My Rollup config builds hundreds of little bundles and they get embedded in server-rendered templates and served-up per page.
But nonetheless, we proceed to see "alternatives to SvelteKit" and it lists build tools... hmmm
Comparing a server backend to a list of build tools seems odd to me.

I am aware that FOSS software owes me nothing.
I am not part of this project and have contributed nothing so far, but I wish to communicate what I feel is a jarring discontinuity in how Svelte is communicated which is unfortunately co-incident with a major breaking code version.

I thank all Svelte developers for their hard work until now.

[idleberg]

the style and font of the new docs feel like a downgrade to me

Generally speaking, I'm quite a fan of serif fonts and think the web could make better use of them. In the particular case of the Svelte docs though, I think a font with subtler serifs might have worked better - the font in use feel like it's made for print. Still hoping that I'm getting used to it over time.

An issue with the website that hasn't been mentioned yet is SEO. I'm a huge fan of the tutorial and in the past it often filled some gaps the old documentation had. However, most of the time the result of a search engine points me to a tutorial page rather than the documentation. I'm not sure how to control this, I suppose nobody would want to exclude the tutorial from being indexed.

[aaronpeacock]

Perhaps the most egregious issue with documentation at the moment is the sudden 404 s for all the old Svelte tutorial content on the web.
Everything from cleared REPL/playground demo example thingies, to official tutorial stuff.
Ex:
https://svelte.dev/tutorial/keyed-each-blocks

IMO, it should be a redirect to https://svelte.dev/v3/tutorial/keyed-each-blocks

[Ocean-OS]

Most of the actual docs are redirected (not quite sure about the tutorials). If you want to see the old tutorials, you can go to https://v4.svelte.dev.