[Docs][RFC]: Strategy to maintain working links #11886
Description
Summary and description
Regarding the handling of links there is some room for improvement.
Goals
- Avoid 404 links (or at least be able to recognize and fix them quickly as soon as they are depublished)
- Ensure links to code snippets always refer to the proper lines / intended code snippets
Motivation
It's frustrating for consumers of the docs to click on links which either lead to 404 or (probably even worse) refer to something different than intended by the author(s). Although those make "good first PRs" and thus a low-barrier into the fabulous world of being a Redwood contributor, peoples valuable attention could probably be more effective in other areas 😉
The number of PRs the current situation causes is countless: #751, #5685, #5774, #5896, #8304 #9266, #10505, #10938 #11581, #11772, #11882, …
Possible solutions
Tackling 404s for (non-github) outgoing links
- Set up a CI job that makes HEAD requests to all links in the docs
- ideally automatically create issues for any found ones ("good first issues")
- probably limit that to canary and stable
- Discuss: Can we introduce more stability going forward?
- When linking to something like docs (i.e. Prisma, Storybook, Pino) do we really want to always refer to the latest or can we ensure they match up with the version that is part of the particular Redwood version?
I.e. for Storybook there are different doc links for v6, v7, etc. - When linking to something profound (taking https://xyproblem.info/ as an example, or even more volatile, a blog entry), would it be feasible to link to an archive.org copy straightaway?
- When linking to something like docs (i.e. Prisma, Storybook, Pino) do we really want to always refer to the latest or can we ensure they match up with the version that is part of the particular Redwood version?
Tackling code links (typically github)
- Option A: always link to the tag version that matches the docs version.
- for canary, that is a challenge, also how do we ensure links are updated when new versions appear?
- Idea: scan current docs for
blob/mainand – for instance given current docs are v9 – scan anything that is notblob/9…
- Option B: Always use permalinks
- drawback that it is not easily possible to identify which branch or tag that link belongs to
- Option C: keep linking to the most recent default branch code
- in 2022 the team concluded this internally to always link to the default branch file (instead of using a permalink) this RFC seeks to revisit that stance.
- keeping the current strategy has all the drawbacks that this RFC aims to improve own, meaning the docs' integrity falls apart as time progresses