Skip to content

Link digests between tutorial, guides, and types; and feature summaries #747

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
theetrain opened this issue Nov 1, 2024 · 0 comments
Open

Comments

@theetrain
Copy link

theetrain commented Nov 1, 2024

I've gathered some site feedback from my coworkers and I feel some of them are worth sharing as a single ticket since they impact the reading experience when planned together. If you prefer I split these into separate tickets let me know.

Have tutorial pages link to respective docs

At the bottom of a tutorial page, add a 'read more' section that points to one or more relevant guides in the docs.

Have docs link to respective tutorials

Near the top of a guide or page, include a link to the respective tutorial page to help those get started hands on.

Have guides link to types

On a given guide, wherever types are mentioned, have them link to the respective type.

Example, these could be links to their types:

image

Provide a feature summary per guide

Some guides could benefit from a <table> or feature summary. For example when referencing form actions, it takes a bit of work to know the difference between use:enhance, applyAction, and update. A table could help as an addition to the explanation of those features, like so:

When supplying a function to use:enhance, its callback function behaviours are:

effect default (no method) update applyAction
reset form no yes no
call invalidateAll no yes no
call goto no yes only when result.type === 'redirect'

Also related: sveltejs/kit#11823

Provide a types index per guide

Somewhere on a given page, such as 'loading data' or 'form actions', provide a link farm or index that lists all related types so they can be looked up easily.

Optionally display inherited types

On a given types reference, display all inherited types or optionally hide them behind an accordion. For example, ServerLoadEvent extends RequestEvent and it would be useful to see the provided features of RequestEvent such as fetch or setHeaders while browsing ServerLoadEvent.

What's often the case is we're in VSCode previewing the event type for +page.server.js@load and we then look up the type for ServerLoadEvent only to hunt for all its types and features. Similarly, if a reader can jump from the "Loading Data" guide to ServerLoadEvent, then it may take some adjustment (or readjustment on a subsequent visit) to learn about its inherited properties.

@linear linear bot added the svelte.dev label Nov 5, 2024
@linear linear bot closed this as not planned Won't fix, can't repro, duplicate, stale May 6, 2025
@Rich-Harris Rich-Harris reopened this May 6, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

2 participants