Feedback: Docs are hard to use

[bmulholland]

I'm starting with Vue Router and having a hard time finding what I need. In this post, I'll try to document all the things I've tried to look up and how I've done that. I'm sure I'm not the only one with these issues, so hopefully fixing them will help others. No need to answer any of these questions, this is purely user feedback on the docs that I hope can inform improvements to the docs to make it easier for others.

1. I have a hard time telling query params apart from the other similar concept but with a different name... named params? I forget... and there's no solid explanation of that anywhere that I've found.
2. Several times, I've wanted to look up the format for using query params. What's the syntax in router.push? How do I fetch the values in my component? So I search for query which gives me... nothing useful?

• There's the Introduction page, which is just that text (couldn't this be a link to the relevant docs? That would be a handy reference!)
• There's several results for the API docs, like https://router.vuejs.org/api/interfaces/RouteLocationNormalizedLoaded.html#query, and none of those provide the information I'm looking for.
• Clicking around these results is even more confusing. What's LocationQuery vs LocationQueryRaw? Why should I care? When?
• Okay, so anyway, after much searching around I find a reference to push that describes the first param of .push to be LocationQueryRaw (though I also found one that just said it's a string? Confusing!).
• Okay, so I'll look up LocationQueryRaw -- but that doesn't tell me its format? How do I set a query using it?
• It looks like maybe I have to look up a sub-type, such as RouteLocationNamedRaw, but that isn't linked, so I have to do a search to find it... Except there's no other results for RouteLocationNamedRaw!! How do I figure this out?? Totally blocked now.
• Okay so back to looking up the docs for .push. Maybe there's some examples? Okay I found https://router.vuejs.org/guide/essentials/navigation.html#Navigate-to-a-different-location which has examples, mentions query and shows how it's different than params (though I naturally also call them "query params" so the naming is super confusing).
• Now all I need to know is how to read those values. I look in the sidebar and... nothing seems to match? I checked out Composition API and that doesn't show a usage of reading the values of the route.
• So then I search for useRoute and find the indirect link to https://router.vuejs.org/api/interfaces/RouteLocationNormalizedLoaded.html which lists query, great. But do I access the values directly, like useRoute().query.key? There's no examples. And opening the return type for query, https://router.vuejs.org/api/#LocationQuery, just has technical details that I'm not 100% confident I understand. I guess I'll just test it?

[posva]

Thanks for the feedback. This is really useful to me!

I have planned to rewrite the Router docs for years. Take a different path to teach the routing concepts, in an order that makes sense when building an application, move to script setup by default, use composition API by default, add cookbook entries, etc. But I've never found the time to actually do it... The truth is that I barely have any companies sponsoring my work (which is far from being limited to Vue Router), yet the router by itself is already a crucial part of Vue applications. And I have been maintaining it for 5 years but I don't think I have done a good job of finding companies to sponsor me.
So I have focused the limited time on other critical aspects like the Data Loaders and on my Mastering Pinia course to create some very needed revenue. I feel like I have failed I haven't succeeded yet in building a recurring income to spend the time I want to dedicate to Open Source. This is not preventing me from contributing, it's only making it slower. I think that giving more visibility on my priorities regarding open source and help me build momentum with people willing to contribute to the project (Vue Router has very few contributors) and accelerate the whole process, improving the long-term quality of the library and, therefore, the Vue Ecosystem.

I'm pinning this issue to gather more feedback and to share and discuss renewed organizations of the Router documentation.

[bmulholland]

Hey posva, thanks for the thoughts. Glad it's useful. I'll continue to post more feedback about the docs here, as I have it.

I totally hear you re: needing to spend time on revenue-generating work. What would you think about starting another discussion to talk about that? A couple quick parts come to mind: 1. Yes, increasing visibility of your need for support to put more work into vue-router, and, 2. perhaps there's high-leverage work you can do to enable more contributors? For example, writing a task list with approachable things new joiners could take on.

[posva]

2. perhaps there's high-leverage work you can do to enable more contributors? For example, writing a task list with approachable things new joiners could take on.

Totally but first, I need to have tasks that can be contributed by new joiners. For example: once I write (and discuss, which is already a contribution) a new plan, I could ask for contributions on sections of the docs.

What would you think about starting another discussion to talk about that?

I'm of course open to having a discussion in the repository about it. I don't know if it's the right place but I really appreciate anybody wanting to help with ideas!

Thanks for the sponsorship BTW ❤️

[bmulholland]

Another one: it took me weeks, until this very moment, to realize that Nested Routes are the best way to implement common layouts. I looked first for references to layouts, templates, something like that, and couldn't find it. So I came up with a complex different way of managing layouts, but which reset the entire layout state on page nav (notably, removing all notification messages).

A page that outlines common tasks (like using layouts) and just a few sentences about how to do each would have been really helpful here.

[bmulholland]

Two common things in a similar area that I struggled to figure out: how to make an error page (not just for 404s, but 500s with an error message passed in), and how to make a nested route for the root route (have to set path for parent and child both to a blank string).

[posva]

Some thoughts: In Vue Router there are two tools for layouts (apart from meta which can be used for anything): Named Views and Nested Routes. I think that layouts are common enough to be interesting for anybody and also it could be useful as a path of teaching Named Views and Nested Routes. In other words, it could be a tutorial to explain these two concepts

[posva]

Two common things in a similar area that I struggled to figure out: how to make an error page (not just for 404s, but 500s with an error message passed in), and how to make a nested route for the root route (have to set path for parent and child both to a blank string).

I find this kind of thing difficult to document in Vue Router because some parts are out of scope and could be very different depending on what the user is doing. e.g. an SPA doesn't have a 500 (except in APIs)

What kind of scenario are you thinking about? with 500? Isn't it more about Error pages in Nuxt or Error boundaries in Vue with onErrorCaptured

and how to make a nested route for the root route (have to set path for parent and child both to a blank string)

I didn't understand this. Do you have an example, maybe?

[bmulholland]

could be useful as a path of teaching Named Views and Nested Routes

Yep, love this idea. Could also be a good way to explore the tradeoffs of each approach, since there's context in which to discuss it.

some parts are out of scope

Yeah... this is a general problem I'm seeing in the Vue ecosystem: there's documentation on the individual packages, but the integration between them isn't covered well. That means that common tasks that most developers would need to do aren't covered well. Another example is setting dynamic page titles: it's not really vue-router, but it's not really anything else, so there's no docs on doing that. I see why it's like this, to be clear, it's a tricky situation. I'd love to discuss that general topic somewhere, though I'm not sure where's appropriate, or who to talk about it with, really.

more about Error pages in Nuxt or Error boundaries in Vue with onErrorCaptured

Yeah actually, I'm migrating a Nuxt 2 app to raw Vue 3/Vite, and needing to replace my Nuxt Error page. That concept is exactly what I want, but in Vue. As you note, there's onErrorCaptured, but wow, what a set of logical jumps needed to get from that low-level hook to the implementation of an error page. I find it overwhelming when also learning all the other concepts at the same time. I wish something would make it easy: "you want a 500 page? Add this code and that code and then run Vue.error or whatever and it'll show the error page with the info you pass it."

"a nested route for the root route" -> Do you have an example, maybe?

Yep! I'm using Nested Routes for templates/layouts in my app. I have a root page (/) that's accessible to logged-in users. It needs the usual logged-in layout, showing a sidebar etc. So: I need to render a nested route at "/". How do I do it?

Looks like this:

const routes = [
  {
    path: "<what goes here?>",
    component: () => import("~/layouts/default.vue"),
    children: [
      {
        path: "<what goes here?>",
        component: () => import("~/pages/index.vue"),

Through experimentation, I found that the only way for both the layout and the page to be rendered at the "/" route is for both paths to be a blank string. My natural inclination was to put one or both as "/", especially since the docs for Nested Routes note "nested paths that start with / will be treated as root paths" which sounds like exactly what I want. But that doesn't work. (This is the sort of thing that I find annoying but can surmount, because I've been doing this a while, but I imagine a more junior dev would really struggle with.)

[scottdotjs]

I'm struggling from the very first page, "Getting Started". It starts with an example of using the router on an HTML page and mentions components called router-link and router-view - do you get those automatically when importing vue-router as a script? Maybe, but it's not specified. But I'm not using Vue in an HTML page, so moved to the section titled JavaScript. It's apparently talking about main.js, and assumes that you know that (I started learning Vue literally today and would prefer the documentation not to assume anything). That example then mentions VueRouter without having actually imported it. Do I also need to import that in my components? Presumably. Why are router-link and router-view named in lowercase with hyphens? Who knows? Then the first link underneath the code sample goes to a page in the "advanced" section. The example structure given here is also completely different from what you get when using create-vue (the recommended way to instantiate a Vue project) and select the option to include vue-router.

This is a very poor experience for beginners. At this point I was immediately discouraged from continuing to read this documentation any further and resorted to finding a third-party tutorial instead - this one, which wasn't the most attractive to look at but did lay out everything step by step in a way that made sense to describe as "getting started".

[skirtles-code]

The Getting Started page was updated in #2174, which is now deployed to the live docs. I tried to incorporate some of your feedback into that rewrite.

If you have time to give the new page a read, I'd welcome any thoughts on ways it could be improved further.

[scottdotjs]

Thanks very much! It's so much better now. I particularly appreciate that you addressed my concerns and added an explanation of global registration and component naming styles, giving learners a solid foundation to build upon rather than relying on assumptions or cross-referencing is a crucial part of a good "getting started" page.

[posva]

I'm going tho throw in here other ideas when I found them:

• Default child not shown when using router-link with name instead of path #2213: the named routes could include a whole section about bypassing path ranking:

  • Allows going to a not found page in a navigation guard
  • display a parent without its children

  These are all edge cases but there aren't documented at all