Hacker News Reader

Comment by grhmc | Hacker News Reader

Thanks for this. Our goal is to keep people on the "rails" of the quick start, with the Concepts as a way to fill out knowledge people are curious about. I wonder if we should downplay the concept docs in service of that? Or put more CTA's to go take the quickstart?

View on HN

If thats the intent, then it seems the Quick Start is what I'd adjust to be more linear then : )

Again, it looks like a basket of equally-weighted links that a user is free to click into at leisure. It seems more like a directory of useful links rather than a "highly opinionated" guide to get me from zero to proficient.

Compared to something like the sveltekit docs [1] (randomly pulled because I was viewing it today) its much easier to understand the flow of topics, and I think a user can assume they should read them in the presented order unless they understand a given topic already.

[1] - https://kit.svelte.dev/docs/introduction

Actually I just realized I was confused because of the homepage styling. On the homepage it has the "quick start" pill in an active state, which I thought meant I was already _on_ the quick start page. It turns out you click that to actually view page 1 of the quick start. But on that page the "linear list of topics" is only shown when clicking the quick start in the header nav. I would add that to the sidebar by default.

Yeah “Quick Start” is really a misleading title for this “section” as it is really the meat of the site itself.

If that’s the intention the naming of the quick start misleads me. I typically skip the example at the beginning of documentation and go straight into the meat of it. In this case it sounds like I inadvertently skipped the main content.

I like the idea of having a flow through, at least, some of the concepts in the order they should be introduced.

Reply on news.ycombinator.com