reactjs / reactjs/react.dev

Move Suspense introduction to the main docs repo

Open
#4,601 0 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
11.8k
Forks
7.9k
Avg merge
1d 11h
Merged PRs (30d)
11

Description

I asked for this before, but the official docs should not lightly link to external articles to explain basic React concepts, because external articles cannot be translated.

Currently, this external RFC, available only in English, is somehow treated as the "official get-started guide" for Suspense, useTransition, etc. It is linked from many pages in the main docs, including recent blog articles. On the other hand, information in the current docs is limited, and they do not explain a Suspense forms a "catch block (boundary)", for example. It's hard for non-English speakers to understand how to use the new concurrent features now.

The React team even deleted the old Concurrent Mode docs without providing alternative articles, which means the most comprehensible introduction for Suspense is now lost at least in my language. I understand they were outdated, but they were better than nothing. The removed files are redirected to 17.reactjs.org, but 17. is not available in other languages.

Please consider the following:

  1. Copy the contents of the RFC to somewhere in the main docs so that translators can work on them.
  2. Meanwhile, restore the Concurrent Mode docs and revert the redirects so that non-English speakers can read them again. It's fine to warn they are severely outdated, but there is no reason to make them completely unavailable in other languages.

Contributor guide

Open the contributing guide

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 reading the linked Suspense RFC and the removed Concurrent Mode documentation referenced in the issue, then inspect how the main docs link to them and where the redirects are configured. Determine whether the RFC can be adapted into translatable main-repo documentation and whether restoring the old pages is still appropriate; done means the agreed introduction and redirect behavior are available to translators.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, react
Domain
documentation, localization
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.