sveltejs / sveltejs/svelte.dev
Link digests between tutorial, guides, and types; and feature summaries
Nobody has claimed this yet.
- 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:
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) updateapplyActionreset form no yes no call invalidateAllno yes no call gotono 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
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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