Docs "search stats" investigation

[sarah11918]

Hey Team Docs!

We have our first "data dump" of the search terms people have been using on the Docs site. Since we know these are all popular searches, we want to make sure that people are being pointed to the best places in docs to answer their questions.

So, we're looking for interested people to a) try searching some of these terms and b) report back here in a reply re: whether you think our search widget is currently helpful to our readers, returning good results etc.

Of particular interest, things like:

1. How many different pages were represented by these 5 results?
2. Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?
3. Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)
4. Do you think more results would be helpful for this search term?
5. Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

And any other observations are welcome!

This is the list of our most-searched for terms in Docs. It's fine if multiple people report back their observations for the same term, but in the interest of getting as many covered as possible, I'll come back periodically and check ones off this list if at least one person has replied with their observations. (And, I might update and add to the questions above too, as I think of new things, so keep checking back!)

🔍 = carried out before search overhaul; 🔎 = carried out after search overhaul

• image — 🔍
• react — 🔍
• tailwind — 🔍
• props — 🔎
• script — 🔍
• slot — 🔎
• client
• glob — 🔎
• ssr
• mdx
• css — 🔎
• 404
• env
• vite
• build
• svg — 🔎
• vue — 🔍
• sass
• class
• redirect — 🔎
• link
• onclick — 🔍

Others:

• getStaticPaths — 🔎

[the-dijkstra]

I'm gonna go first:

Keyword: onclick

1 - Number of search results

5 results

2 - Was the top result the "best" suggestion ?

No (I would say the 5th result is the closest suggestion)

3 - Was a page entirely missing from the results ?

No

4 - Do you think more results would be helpful for this search term?

I think less results are more helpful for this term, since the results showing now are a bit misleading IMO.

5 - Do you feel that someone looking at the 5 results gets enough info?

I don't think so, I suggest we rank this 2 pages for this keyword to make the results more helpful:

• https://docs.astro.build/en/tutorial/6-islands/2/#add-client-side-interactivity
• https://docs.astro.build/en/tutorial/6-islands/1/#include-a-preact-greeting-banner

[dreyfus92]

A few comments on script keyword:

1.- How many different pages were represented by these 5 results? 5.

2.- Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion? No, I think that there should be results regarding the script tag or showing as the last result TypeScript section.

3.- Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.) No.

4.- Do you think more results would be helpful for this search term? Not really.

5.- Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose? Yeah, I feel like the info is accurate and easy to understand.

[the-dijkstra]

Keyword : image

1 - Number of search results

5, all search results include image keyword in them.

2 - Was the top result the "best" suggestion ?

I would say yes the top results leads directly to the doc page where all information about image can be found.

3 - Was a page entirely missing from the results ?

No, all search results were relevant.

4 - Do you think more results would be helpful for this search term?

I don't think so, No.

5 - Do you feel that someone looking at the 5 results gets enough info?

Even though the first result in the search leads to the entire docs page where all information about Image can be found. I still find other search results good to have as a shortcut for the user if he knows exactly what section he is looking for.

A suggestion that I'm not sure about is whether to rank the 5th result or not (lead users to Image integration).

[the-dijkstra]

Keyword : react

1 - Number of search results

5, only 2 search results are relevant to search keyword.

2 - Was the top result the "best" suggestion ?

Yes. the top result lead to the exact doc on how to add React to Astro.

3 - Was a page entirely missing from the results ?

No. all search results lead to existing pages.

4 - Do you think more results would be helpful for this search term?

In this case only 2 search results are relevant to the react keyword.

5 - Do you feel that someone looking at the 5 results gets enough info?

• IMO the first result for this keyword is enough. other search results are bonus.
• 2 results were not relevant to React, (prefetch, solid)

Note: the search results URL's all include this hash-pound #article which leads to no section on the page. not sure if it's an old URL structure or it's just wrong. the pages work correctly though.

[sarah11918]

Ooh, especially glad someone chose to do script since I just got this week's stats report, and that term jumped up to make it to #1 this week! (And, we know we want to analyze onClick, so great first choice!) 🚀

[the-dijkstra]

@sarah11918 how do you feel about the work already done ?

does it need details ? is it enough for your needs ?

[sarah11918]

@the-dijkstra I'll be looking at this more closely today/tomorrow and will provide some feedback! Sorry, didn't mean to go radio silent on you, but was just getting a rather large PR put together this week first. 😄

[the-dijkstra]

haha no worries @sarah11918, I just wanted to make sure we are on a good path. good luck with the the other PR 😄

[sarah11918]

OK, so these are GREAT, and I'm loving the screenshots of the results! @dreyfus92 @the-dijkstra

I mean, I'm not loving the results.. onClick and script are terrible! But this is so incredibly helpful! It's great for docs planning, for sure. I'm hoping more people step up, but as you have time to try more of these, please do! ❤️ 🚀

[dreyfus92]

Keyword: vue

1.-How many different pages were represented by these 5 results? 5.

2.-Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion? Yes it was.

3.-Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.) I don't think so.

4.-Do you think more results would be helpful for this search term? I think that the last 2 results should be changed cause the reference sends you to an icon that appears on the bottom of @astrojs/solid-js and @astro/react guides which doesn't provide you anything relevant of Vue.

5.-Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose? Yeah I think so it is enough, but according to 4th question last 2 results should be changed.

[delucis]

These are so helpful! Thank you all. I hadn’t noticed that weird thing showing in both the react and vue searches that seem to also show pages where react/vue are in the navigation in the page footer. Definitely going to look at fixing that.

[kevinzunigacuellar]

Keyword : tailwind

1. How many different pages were represented by these 5 results?

   There are 2 different pages.

2. Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?

   The top result was the best result in my opinion.

3. Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)

   No, I don't think there are missing pages.

4. Do you think more results would be helpful for this search term?

   I don't think so. The search results cover this term very well.

5. Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

   Yes, I think they get more than enough information.

[sarah11918]

I find it super-interesting that our CSS & Styling page was not a hit for Tailwind! Not bad... just interesting!

[dreyfus92]

Keyword : props

1.-How many different pages were represented by these 5 results?

There are 4 different pages.

2.-Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?

The fourth result is the best result in my opinion.

3.-Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)

No, I don't think there are missing pages.

4.-Do you think more results would be helpful for this search term?

No, I don't think so.

5.-Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

Yes, the results help you get a good grasp of how props work within Astro.

[sarah11918]

I just did getStaticPaths() and I am NOT HAPPY.

Keyword : getStaticPaths()

How many different pages were represented by these 5 results?

There are 5 different pages.

Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?

No. The top 4 results were all error messages. These are helpful to show up, but should they really show up instead of any reference or learn material? Maybe Error messages needs its own category?

The only other result was from the tutorial. The good news is, it's clearly visible that it's from the tutorial!

Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)

Yes, neither the API reference page, nor Routing showed up. (There is a separate open issue re: how we describe getStaticPaths in both of these places, and whether the content is appropriately divided between the two of them. #1733

Do you think more results would be helpful for this search term?

If we're going to be including individual error message pages, then yes! 😅

Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

Nope.

[delucis]

Oh, interesting. Looks like those error pages are categorised as “Reference” whereas I thought we had decided to give them their own dedicated “Error Reference” category we could de-prioritise.

I think if we make sure that’s the case, the relevant getStaticPaths reference should float up the results. But still a question whether we can get the routing docs to rank better for this.

^{Is getStaticPaths a common query? It’s the 45th most common over the last 30 days, with around 100 searches in that time.}

[BryceRussell]

Keyword: slot

How many different pages were represented by these 5 results?

2 different pages

Was the top result the "best" suggestion? If not, was the first search term result at least a "good" suggestion?

Currently the top result is the 'invalid slot name' error page which is not the best result, I feel like the slot results in order of importance are something like:

1 (Learn Tab) <slot />, named slots, fallback
2 (Refrence Tab) Astro.slots API
3 Slot tutorials
4 'invalid slot name' error page

Was a page entirely missing from the results that probably should have been included?

No

Do you think more results would be helpful for this search term?

No, all results are there they just need to be shifted upwards by deprioritzing the error page

Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

No, I think most people searching the term 'slot' are looking for information about <slot /> and named slots, but the first 2 results are taken up by the 'invalid slot name' error page

[delucis]

Update re: getstaticpaths and slot keywords. The error references are now correctly categorised to separate things out a bit more clearly. Unfortunately we’re still running into the issue we’ve encountered previously that while we can demote pages with Algolia’s pageRank, because errors often include the term in the page title vs in a subheading in docs, those are still considered more relevant results:

Ideas welcome here and will continue to think on this myself.

[Tyson910]

How many different pages were represented by these 5 results?

4 Project structure, Imports (static assets section), Routing, & Migrating from SvelteKit

Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?

No, favicon.ico is relevant and belongs in the search, but I feel like the images & static assets page should be number one.

Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)


I think adding the image guide https://docs.astro.build/en/guides/images/ could be helpful. Depending on use case, svgs can be used with the Astro/Image component. Plus, the page has multiple examples of how to work with svg’s in Astro

Do you think more results would be helpful for this search term?


In this case I could only find 3 search results are relevant to the svg keyword.

Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

IMO the first two results are good. The third result links to the routing page b/c it just so happens to contain “svg”. I’m assuming the last two are there in case of a svelte typo? (“Migrating from SvelteKit” & “Similarities between SvelteKit and Astro”)

[Tyson910]

How many different pages were represented by these 5 results?

2 - Error Reference & API reference

Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion?

No, I don't think giving a such a specific error message should be in the top 5 results. I feel like the Astro.glob section of the imports page OR the Astro.glob API reference should be number one.

Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.)

I think adding both the Astro.glob section of the imports page page AND the RSS guide to using glob imports should be in higher in the search results. Another result that could be added could be the Astro.glob() - no matches found section of the troubleshooting page

Do you think more results would be helpful for this search term?

No, I don't think so

Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose?

Yes, for the most part. I think the API reference section gives a good idea of how to use Astro.glob()

[Jothsa]

CSS

1. How many different pages were represented by these 5 results? 2 separate pages, "Styles and CSS" and the "Imports" page.

2. Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion? Yes, the "Styles and CSS" page is very comprehensive and the best suggestion.

3. Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.) Nothing was missing afaik.

4. Do you think more results would be helpful for this search term? No

5. Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose? Yes

[AishaBlake]

I know I'm late to the party but I actually did search some of these in the last couple of days, so adding some notes!

Keyword: redirect

1. How many different pages were represented by these 5 results? 3
2. Was the top result the "best" suggestion (in your mind - the most helpful/general page on the topic)? If not, was the first search term result at least a "good" suggestion? No, I think the sections from the Routing page are what most people would be looking for. It's what I was looking for last night!
3. Was a page entirely missing from the results that probably should have been included? (e.g. You searched for Markdown and did not see "Markdown & MDX" as one of the 5 results.) Maybe the section on Astro.redirect? I think, if someone is just searching for "redirect", they're more likely to want the API reference than the error reference.
4. Do you think more results would be helpful for this search term? Potentially. It would be nice to show something descriptive about Astro.redirect in the results.
5. Do you feel that someone looking at the 5 results gets enough info about each search result to know the best one to choose? Personally, I was looking for info on redirects in the context of switching my site over from Gatsby (and reworking my folder structure as a result). The Routing page had exactly what I needed.

Side note... I'm not sure if this just the style since there's a similar code snippet just before this, but it seems like this code sample should also include astro.config.mjs in the corner. Is that the case?

[sarah11918]

Thanks @AishaBlake ! Great feedback, and yes, we tyically would show the file name there. Would you like to make a PR to docs to add that? You can find the syntax we use for our code samples here: https://github.com/withastro/docs/blob/main/contributor-guides/writing-and-style-guide.md#code-samples

If not, no worries! I'll add that to to the stack of tasks!

[AishaBlake]

Thanks @AishaBlake ! Great feedback, and yes, we tyically would show the file name there. Would you like to make a PR to docs to add that? You can find the syntax we use for our code samples here: https://github.com/withastro/docs/blob/main/contributor-guides/writing-and-style-guide.md#code-samples

If not, no worries! I'll add that to to the stack of tasks!

No problem. PR is up! #3992

[sarah11918]

Retiring this issue for now! 🫡

It has served us well, and we will think of things to do in the new year!