sveltejs / sveltejs/svelte.dev

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

Open
#747 0 comments 6 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs (content)
Dominant language
Svelte
Stars
330
Forks
278
Avg merge
2d 2h
Merged PRs (30d)
29

Description

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: https://github.com/sveltejs/kit/issues/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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the tutorial pages, guides, and type references described in the issue, along with related issue #11823. Map the requested links, feature summaries, type indexes, and inherited-type display across those page types. Done means the agreed documentation relationships and summaries are implemented consistently and are easy to verify while browsing.

Written by the indexing model from the issue text.

Assessment

Domain
content, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.