Skip to content

docs: improve clarity in guide documentation#6479

Merged
chenjiahan merged 4 commits intomainfrom
copilot/improve-english-docs
Nov 1, 2025
Merged

docs: improve clarity in guide documentation#6479
chenjiahan merged 4 commits intomainfrom
copilot/improve-english-docs

Conversation

Copy link
Contributor

Copilot AI commented Oct 31, 2025

Rewrote sentences in 5 English documentation files to sound more natural and professional without changing technical meaning.

Changes by file

  • guide/start/index.mdx: Simplified comparisons ("on par with" → "comparable to"), fixed hyphenation ("blazing fast" → "blazing-fast"), applied sentence case to feature headings
  • guide/start/quick-start.mdx: Streamlined terminology ("npm dependencies" → "dependencies", "development server" → "dev server"), made CLI descriptions more concise
  • guide/advanced/browser-compatibility.mdx: Replaced awkward constructions ("lower-version browsers" → "older browsers"), tightened technical explanations in syntax transpilation and API polyfill sections
  • guide/basic/html-template.mdx: Improved phrasing ("on route changes" → "when routes change", "build process" → "build")
  • guide/faq/general.mdx: Fixed parallel structure in comparative descriptions

Example change

- Rsbuild is a build tool on par with Vite, Create React App, and Vue CLI.
- All come with built-in dev servers, command line tools, and sensible build
- configurations for an out-of-the-box experience.
+ Rsbuild is comparable to build tools like Vite, Create React App, and Vue CLI.
+ All include built-in dev servers, command line tools, and sensible build
+ configurations for an out-of-the-box experience.

All changes preserve original technical accuracy while improving readability for both native and non-native English speakers.

Original prompt

Improve the English docs in website/docs/en. Many paragraphs were
translated from Chinese and may sound unnatural.

  Rewrite sentences that don't read like authentic, professional English —
  **without changing their meaning** — so they match the tone of
  high-quality open-source docs.


  - **IMPORTANT:** Only change a sentence if it clearly improves clarity or
  correctness.

  - **IMPORTANT:** Don't alter the original meaning.

  - If you edit files in `docs/en`, check the same files in `docs/zh` to see
  if similar updates are needed.

  - Use clear, simple language for non-native English readers.

  - Keep reasonable technical abbreviations (e.g., `dev server`).

  - Use sentence case for Markdown headings.

  - Don't change more than 5 files in one PR.

  - Start PR titles with `docs:`.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

@netlify
Copy link

netlify bot commented Oct 31, 2025

Deploy Preview for rsbuild ready!

Name Link
🔨 Latest commit a5ea49a
🔍 Latest deploy log https://app.netlify.com/projects/rsbuild/deploys/6905c79df66d53000894c4af
😎 Deploy Preview https://deploy-preview-6479--rsbuild.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 59 (🔴 down 10 from production)
Accessibility: 97 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: 60 (no change from production)
View the detailed breakdown and full score reports

To edit notification comments on pull requests, go to your Netlify project configuration.

@CLAassistant
Copy link

CLAassistant commented Oct 31, 2025

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ chenjiahan
❌ Copilot
You have signed the CLA already but the status is still pending? Let us recheck it.

Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Copilot AI changed the title [WIP] Docs: Improve English clarity in website documentation docs: improve English clarity in guide documentation Oct 31, 2025
Copilot AI requested a review from chenjiahan October 31, 2025 23:47
@chenjiahan chenjiahan marked this pull request as ready for review November 1, 2025 05:33
Copilot AI review requested due to automatic review settings November 1, 2025 05:33
Copy link
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull Request Overview

This PR refines the English documentation to improve clarity, conciseness, and consistency throughout the guide. The changes are primarily editorial, focusing on more natural phrasing and clearer technical communication.

Key changes:

  • Simplified and shortened phrases for better readability (e.g., "npm dependencies" → "dependencies", "various higher-level tools" → "higher-level tools")
  • Improved consistency in terminology (e.g., "dev server" throughout instead of "development server")
  • Enhanced clarity in technical explanations (e.g., rephrasing comparisons and feature descriptions)

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.

Show a summary per file
File Description
website/docs/en/guide/start/quick-start.mdx Streamlined setup instructions and template descriptions for brevity
website/docs/en/guide/start/index.mdx Improved phrasing in introduction, comparisons, and feature descriptions
website/docs/en/guide/faq/general.mdx Minor grammar improvements for better flow
website/docs/en/guide/basic/html-template.mdx Clarified template engine and configuration descriptions
website/docs/en/guide/advanced/browser-compatibility.mdx Enhanced technical explanations for syntax and API compatibility

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

@chenjiahan chenjiahan changed the title docs: improve English clarity in guide documentation docs: improve clarity in guide documentation Nov 1, 2025
@chenjiahan chenjiahan merged commit 783ff2f into main Nov 1, 2025
11 of 12 checks passed
@chenjiahan chenjiahan deleted the copilot/improve-english-docs branch November 1, 2025 08:47
@chenjiahan chenjiahan mentioned this pull request Nov 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants