facebook / facebook/lexical

Feature: Plan for versioned documentation

Open
#6,144 2 comments 1 reaction 0 assignees View on GitHub
documentation enhancement infra
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.