Skip to content

docs: improve documentation clarity and naturalness#6354

Merged
chenjiahan merged 5 commits intomainfrom
copilot/improve-english-docs
Oct 14, 2025
Merged

docs: improve documentation clarity and naturalness#6354
chenjiahan merged 5 commits intomainfrom
copilot/improve-english-docs

Conversation

Copy link
Contributor

Copilot AI commented Oct 13, 2025

Summary

This PR improves the clarity and naturalness of the English documentation in website/docs/en. Many sentences were originally translated from Chinese and contained unnatural phrasing, grammatical issues, and inconsistent voice. These improvements make the documentation read like authentic, professional English while preserving all technical meaning.

Changes

Updated 9 documentation files with targeted improvements:

  • guide/advanced/env-vars.mdx - Enhanced phrasing and consistency throughout environment variable documentation
  • config/server/open.mdx - Clarified browser configuration and server opening instructions
  • config/environments.mdx - Improved environment naming guidelines
  • guide/start/index.mdx - Refined feature descriptions and comparison sections
  • guide/basic/static-deploy.mdx - Streamlined deployment instructions for multiple platforms
  • guide/optimization/code-splitting.mdx - Polished technical descriptions of splitting strategies
  • guide/basic/output-files.mdx - Enhanced output directory explanations
  • config/performance/chunk-split.mdx - Clarified chunk splitting configuration options
  • config/output/filename.mdx - Improved filename configuration descriptions

Types of Improvements

Grammar and Articles

  • Corrected article usage (a/an/the): "After the production build" → "After a production build"
  • Fixed noun forms: "all codes" → "all code"

Voice and Consistency

  • Standardized on "you" voice instead of "we": "we set" → "set", "we can access" → "you can access"
  • Applied sentence case to headings: "Easy to Configure" → "Easy to configure"

Natural Phrasing

  • "thoughtfully designed default build configurations" → "carefully designed default build configuration"
  • "fully unleashes Rspack's performance" → "fully leverages Rspack's performance"
  • "eliminates the need to manually set it" → "you don't need to set it manually"

Professional Vocabulary

  • "allows using" → "supports using"
  • "a large number of" → "numerous"
  • "may decrease" → "may degrade"

Prepositions and Structure

  • "used for directory names" → "used in directory names"
  • "alias of" → "alias for"
  • Improved sentence flow: "This config will be merged" → "This configuration will be merged"

Verification

  • ✅ All changes preserve technical accuracy and meaning
  • ✅ No code examples or configuration values were modified
  • ✅ Prettier formatting applied
  • ✅ Spell checking passed
  • ✅ Chinese documentation reviewed (no changes needed as source material)

The documentation now reads more naturally for native and non-native English speakers while maintaining the same technical precision and helpfulness.

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 10 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 13, 2025

Deploy Preview for rsbuild ready!

Name Link
🔨 Latest commit be0c9b9
🔍 Latest deploy log https://app.netlify.com/projects/rsbuild/deploys/68edb5b29afa4e0008899a57
😎 Deploy Preview https://deploy-preview-6354--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: 75 (🔴 down 3 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 13, 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.

Copilot AI and others added 2 commits October 13, 2025 14:42
Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Co-authored-by: chenjiahan <7237365+chenjiahan@users.noreply.github.com>
Copilot AI changed the title [WIP] Docs: Improve clarity and correctness of English documentation docs: improve English documentation clarity and naturalness Oct 13, 2025
Copilot AI requested a review from chenjiahan October 13, 2025 14:46
@chenjiahan chenjiahan changed the title docs: improve English documentation clarity and naturalness docs: improve documentation clarity and naturalness Oct 14, 2025
@chenjiahan chenjiahan marked this pull request as ready for review October 14, 2025 02:30
Copilot AI review requested due to automatic review settings October 14, 2025 02:30
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 improves the clarity and naturalness of English documentation across 9 files in the Rsbuild project. The changes address unnatural phrasing that resulted from Chinese translations, making the documentation read more professionally while preserving all technical accuracy.

Key improvements include:

  • Standardizing voice and consistency (using "you" instead of "we", applying sentence case to headings)
  • Correcting grammar and article usage throughout
  • Replacing unnatural phrases with more professional vocabulary

Reviewed Changes

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

Show a summary per file
File Description
guide/optimization/code-splitting.mdx Enhanced technical descriptions of chunk splitting strategies and performance considerations
guide/basic/static-deploy.mdx Streamlined deployment instructions and improved clarity of platform-specific steps
guide/basic/output-files.mdx Refined explanations of output directory structure and asset organization
guide/advanced/env-vars.mdx Improved environment variable documentation with clearer examples and usage patterns
config/server/open.mdx Clarified browser configuration options and server opening instructions
config/performance/chunk-split.mdx Enhanced chunk splitting configuration descriptions and parameter explanations
config/output/filename.mdx Improved filename configuration explanations and async module handling
config/environments.mdx Refined environment naming guidelines with clearer recommendations

Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.

@chenjiahan chenjiahan merged commit 4dd1ef6 into main Oct 14, 2025
10 of 11 checks passed
@chenjiahan chenjiahan deleted the copilot/improve-english-docs branch October 14, 2025 02:32
@chenjiahan chenjiahan mentioned this pull request Oct 30, 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

Comments