Describe the problem

I apologize for the length of this post, feel free to skip to the last section where I make the suggestion, but first, a worked explaination of how I, someone who is not familiar with modern web dev, struggled with the documentation. (I'm normally in applications dev).

My workthrough:

I was attempting to use a route parameter, ie, the parameters that are in the form of foo/bar/[name]/baz, where name is a route parameter.

I first attempted to see how to access this in the documentation, at https://svelte.dev/docs/kit/advanced-routing

however, nowhere in this page does it describe how to actually access these parameters and I am very new to svelte, so I looked at the tutorial here: https://svelte.dev/tutorial/kit/params where it seems to call this parameter "slug".

However, this page doesn't actually explain how to get this value either, but it does say that this is shown in the next page, and then I got fairly confused.

All I want to know is how to get the route parameters! none of this extra stuff on the side.

So I skimmed down to the server.js file which is as below:

import { posts } from './data.js';

export function load() {
	return {
		summaries: posts.map((post) => ({
			slug: post.slug,
			title: post.title
		}))
	};
}

And I'm confused. I'm trying to find out how to read the route parameters, and yet here, it just assigns a different parameter (also called slug).

Infact, I think there's three entirely separate concepts being shown here, all of which is called a "slug":

• There's the data returned from the load function, which seems to contain data from an unrelated file (called data.js).
• This data is mapped using a lambda, however this mapping does not use the route parameters. It uses only the post parameter, but not the HTTP post, instead, this is the post from data.js.

I have to look further below and find another server.js file that is as follows:

import { posts } from '../data.js';

export function load({ params }) {
	const post = posts.find((post) => post.slug === params.slug);

	return {
		post
	};
}

And aha! Here, there's load function, this time with a parameter called 'params', and this one contains the slug.

The request

When it comes to documentation, could we avoid overloading the names so much - the overloaded names make sense in the code, but when you're trying to learn and read documentation it's confusing.

Several examples:

1. Post. We have 'data.js', which is loaded as "post" data. This is confusing because this isn't the actual HTTP post, but apparently is conceptually considered to be the page post data in the tutorial.
2. Slug. This is either the route's route parameter called "slug", or it's the slug that's in the post data, which is actually the data.js file. Or it's the slug returned by the various server load functions.

It would have been clearer, at least for me, if instead, we had:

A data.js file, that was NOT referred to as "post". Perhaps this could be referred to instead as 'notes', just to make it different.
The "slug" references in this file should probably be called "keyword", or again, something other than slug, because this slug is not the actual route parameter.
And the 'slug' returned by one of the server load functions should be called again something else - actually would be OK to call this one 'keyword', too, because this one does actually represent the keyword in the data.js file.

That way I would've been able to jump straight to "slug", and then realise that "Hmm, so the route param is called slug, this is mapped to each note in the notes that are in data.js. And the server load function locates which post has a keyword that matches the slug value in the route param, and returns that.

Much clearer than: "The server load function loads the POST data, and provides the SLUG. The other server function loads the SLUG, and returns a SLUG if it matches the POST's SLUG". When you're not familiar with the jargon, the overloaded words are confusing.

I now know how to read the slug from the route parameters, so I'm ok now, and now that I know how to read those route parameters, I now can make sense of the tutorial and I am now ready to hook it up into the database.

Describe the proposed solution

I want to see the concepts overloaded much less. So that if there's a "slug" in the route parameters, then the only thing that's ever called a "slug" is that route parameter.

Alternatives considered

No response

Importance

nice to have

Additional Information

No response