Feature: Plan for versioned documentation
- Dominant language
- TypeScript
- Stars
- 23.9k
- Forks
- 2.2k
- Avg merge
- 1d 16h
- Merged PRs (30d)
- 61
Description
Currently, all documentation is generated whenever main is deployed. This can be confusing for users when there are new APIs or deprecations such that the documentation does not match the behavior or features of the latest released version.
A short-term plan might be to simply mark the documentation website (and playground) with some information that lets users know that the documentation reflects main and may not be available in a released version. Docusaurus does this with a note:
> This is unreleased documentation for Docusaurus Canary 🚧 version.
> For up-to-date documentation, see the [latest version](https://docusaurus.io/docs) (3.3.2).
Longer term, whenever the API is considered stable, it would make sense to have multiple doc website available (e.g. 19.react.dev, 18.react.dev) or to use [docusaurus versioning](https://docusaurus.io/docs/versioning). Some possibilities for interim middle-ground solutions:
* Start marking methods/features with a [@since](https://jsdoc.app/tags-since) tag, although that wouldn't necessarily cover deprecations where the example code changes to match main in a backwards incompatible way (as in #6141 or #6158)
* Always deploy two doc websites, one for main (maybe call this next or canary) and one that reflects the latest released version.
Contributor guide
Research direction
Start by reviewing how the documentation website and playground are currently generated and deployed, then compare the proposed interim notice, @since tags, and separate versioned sites. The issue is complete only when the project has an agreed, implementable plan for distinguishing unreleased documentation from the latest released version.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100