Situation:
Followed the install docs to the wizard for a plain HTML site (a static GitHub Pages portfolio - no framework). The opening screen offers two routes, a GitHub PR or a terminal command, and neither fits. In the terminal, the framework picker has no "plain HTML / static site" option, so a first-time user with a static site ends up staring at a list where nothing applies.
Solutions:
My correct path turned out to be the JS snippet - a single paste into the head. Technically that lives behind the "Web" tile in the SDK grid, but nothing tells you that. If I see "Web" I think React, JavaScript, Java - something more technical - not "here's the JS snippet you need for your HTML." Every option in that grid is the web, so the label only makes sense once you already know the SDK taxonomy, which is exactly the person who doesn't need the signpost. I only worked it out by digging through the docs afterwards.
Concern/Effect:
Static sites are a really common first-contact case - portfolios, landing pages, docs sites. Right now that entire group gets routed into a tool that can't help them, with no signpost to the correct tool for their use case. Which might make them bounce off first instinct if not presented with the options. The options are there in the docs, but you have to go digging for it, which shouldn't be the case when it comes to first touch onboarding.
Set Up Manually, brings you to SDK's which, again, may not be appropriate for the use case. Also, depending on where you are on the technical ladder "set up manually" could be a bit ambiguous. For some people it could be running and configuring within terminal, for others it would be manually placing a snippet into preexisting html. SDK's might not be what people jump to.
Suggested fix:
A "None of these / plain HTML site" option in the picker, and renaming or subtitling the "Web" tile so it says what it is - e.g. "HTML snippet (any website)". Even just a line of text under the wizard command in the docs would do most of the work.
Situation:
Followed the install docs to the wizard for a plain HTML site (a static GitHub Pages portfolio - no framework). The opening screen offers two routes, a GitHub PR or a terminal command, and neither fits. In the terminal, the framework picker has no "plain HTML / static site" option, so a first-time user with a static site ends up staring at a list where nothing applies.
Solutions:
My correct path turned out to be the JS snippet - a single paste into the head. Technically that lives behind the "Web" tile in the SDK grid, but nothing tells you that. If I see "Web" I think React, JavaScript, Java - something more technical - not "here's the JS snippet you need for your HTML." Every option in that grid is the web, so the label only makes sense once you already know the SDK taxonomy, which is exactly the person who doesn't need the signpost. I only worked it out by digging through the docs afterwards.
Concern/Effect:
Static sites are a really common first-contact case - portfolios, landing pages, docs sites. Right now that entire group gets routed into a tool that can't help them, with no signpost to the correct tool for their use case. Which might make them bounce off first instinct if not presented with the options. The options are there in the docs, but you have to go digging for it, which shouldn't be the case when it comes to first touch onboarding.
Set Up Manually, brings you to SDK's which, again, may not be appropriate for the use case. Also, depending on where you are on the technical ladder "set up manually" could be a bit ambiguous. For some people it could be running and configuring within terminal, for others it would be manually placing a snippet into preexisting html. SDK's might not be what people jump to.
Suggested fix:
A "None of these / plain HTML site" option in the picker, and renaming or subtitling the "Web" tile so it says what it is - e.g. "HTML snippet (any website)". Even just a line of text under the wizard command in the docs would do most of the work.