Hacker News Reader

Comment by JamesSwift | Hacker News Reader

UX feedback: for an opinionated guide targeted at newbies, I think the 'concepts' page should be much more of a guided introduction. I click on it and have a big basket of things in _alphabetical order_. I think it should be a top-to-bottom ordering of how a user should read them if encountering for the first time. Maybe have a separate glossary page if thats what you are going for with the alphabetical order.

View on HN

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?

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.

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.

Reply on news.ycombinator.com