Showcase features on our docs front page

[hippotastic]

Current situation

Here's a likely user journey: Coming from the main astro.build site, readers could already see a brief intro to what Astro can do for them and some USPs. Then they click on the gigantic "Read the docs" button and land on our docs front page (a.k.a. "Getting Started").

This page is our main entry point to the docs, and it seems to be primarily focused on getting users to try Astro immediately.

However, when we think about our reader's state of mind here, they may not be convinced yet that they actually want to try Astro right now. They are generally interested to see how Astro works, but they may be like me and want to get quick answers to some key questions first before giving it a try.

Key questions

Here's my mindset when I first stumbled onto Astro and looked at the docs:

• What does the Astro syntax look like? Do I like it, does it feel familiar?
• How much/few boilerplate code is required for a simple site with 3 pages or so?
• Does it support all the features I need for my project?
  • pulling in content from Markdown or maybe external sources
  • components
  • multiple layouts
  • optimized images
  • SEO
  • analytics support
  • i18n
  • blog stuff like listing the most recent X posts, index/archive pages with pagination, tag/category pages
• What is the dev experience like? Tools, syntax highlighting, useful error messages?
• What is the best way to start experimenting with Astro?

In my opinion, the current Getting Started page only answers the very last question - how to get started RIGHT NOW. Everything else is not quite there yet, and most importantly - there is NO CODE! 😄 I can't get a feel if I like Astro if I don't see any code.

Possible solution

I'd love to get answers to those key questions in quick, punchy form, but not with a marketing focus (that's what the main astro.build page is already doing), but with a code focus.

So, yes please, hit me with a quick code snippet for each of the key questions outlined above!

• Astro syntax / "do I need much boilerplate code?"
  • Show me what a valid Astro page looks like!
  • Show me that same snippet with some added variables and/or a simple component.
  • Finally add a frontmatter script that even requests data from an API to show how easy it is to do all that with Astro.
• How to do X in Astro
  • Show an accordion/expandable list of the key feature questions I outlined above, allowing me to see the simple solution for each of those common scenarios in Astro.
• Dev experience
  • Maybe a quick teaser screenshot of VS code with syntax highlighting, IntelliSense etc., link to Editor Support page
  • Fenced code block or screenshot of the shell showing the CLI in action
• Finally the "try it yourself now" section
  • Links to Stackblitz/CodeSandbox
  • Link to our Automatic Installation page

Wherever suitable, we could add links to the related in-depth docs pages for the features we're showcasing. For example, when showing in a snippet how easy it is to add a component, link to the Components page.

[sarah11918]

Thanks, @hippotastic !

I love this feedback, and I would like to also add the "mobile vs desktop" perspective to consider: reasons for hitting the doc site on mobile (ie what the reader intends to DO, SEE and LOOK FOR) may very likely be different than a desktop arrival.

In particular, "TRY NOW" may not be as helpful on MOBILE, but for many desktop users, it will be enticing.

I think, "Find an answer to my immediate question about doing X" is a very common user goal in both cases, but I would also want mobile in particular to be helpful here, since it's a little harder to do EVERYTHING on a phone, anyway.

So, I'd also like us to consider whether we need a separate, or at least slightly tweaked mobile version/strategy.

[hippotastic]

Good point regarding the mobile experience of the "try now" options! It's not fun to use those live editors on mobile, so I think this is another good reason to showcase the key features right inside the docs rather than linking to an online editor.

I'm hoping that we can find a solution that we don't need to tweak much for mobile. Having an accordion to disclose the answers to all the key feature questions (including the respective snippets of those answers) should hopefully keep the page consumable enough on mobile. But we should definitely keep an eye on this!

[sarah11918]

You mentioned teaser screenshots, like an editor with our VS Code extension, which I think (now that we have it and it's so good!) makes a lot of sense. It made me think, now that @Jutanium has started making very short Astro videos that he has been tweeted out, I wonder whether one or two of these on our Docs landing page is helpful?

I also know that we will have a "Why Astro?" page coming, so I do want to make sure that ideas are properly distributed between the landing page, and that page.

[sarah11918]

OK, this one is on my radar this week!

I will be focusing a bit on "The Astro Story" and first impressions. So, I've pinned this discussion and I'll reference this for Team Docs to take a look at. 🚀

[yanthomasdev]

Vitest's features page has a well-animated list of features that brings a lot of attention and links to other relevant pages, would adding something similar to the "Getting Started" page help? Or maybe this would fit better in the "Why Astro?" page, instead?