docs: edit some docs to adjust tone

Author: jderochervlk

markdown-pages/docs/manual/array-and-list.mdx

@@ -10,7 +10,7 @@ order: 12
 
 ## Array
 
-Arrays are our main ordered data structure. They work the same way as JavaScript arrays: they can be randomly accessed, dynamically resized, updated, etc.
+Arrays are the main ordered data structure in ReScript. They can be randomly accessed, dynamically resized, and updated.
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
@@ -82,9 +82,7 @@ myArray[0] = "bye";
 
 ### Array spreads
 
-**Since 11.1**
-
-You can spread arrays of the the same type into new arrays, just like in JavaScript:
+You can spread arrays of the same type into new arrays:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
@@ -96,21 +94,17 @@ let x3 = [...y]
 ```
 
 ```javascript
-var Belt_Array = require("rescript/lib/js/belt_Array.js");
-
 var y = [1, 2];
 
-var x = Belt_Array.concatMany([[4, 5], y]);
+var x = [4, 5, ...y];
 
-var x2 = Belt_Array.concatMany([[4, 5], y, [7], y]);
+var x2 = [4, 5, ...y, 7, ...y];
 
-var x3 = Belt_Array.concatMany([y]);
+var x3 = [...y];
 ```
 
 </CodeTab>
 
-> Note that array spreads compiles to `Belt.Array.concatMany` right now. This is likely to change to native array spreads in the future.
-
 ## List
 
 ReScript provides a singly linked list too. Lists are:

markdown-pages/docs/manual/async-await.mdx

@@ -67,7 +67,7 @@ You will probably notice that this looks very similar to `async` / `await` in JS
 - `await` may only be called on a `promise` value
 - `await` calls are expressions, therefore they can be used in pattern matching (`switch`)
 - A function returning a `promise<'a>` is equivalent to an `async` function returning a value `'a` (important for writing signature files and bindings)
-- `promise` values and types returned from an `async` function don't auto-collapse into a "flat promise" like in JS (more on this later)
+- `promise` values and types returned from an `async` function don't auto-collapse into a flat promise. See the details below.
 
 ## Types and `async` functions
 

markdown-pages/docs/manual/browser-support-polyfills.mdx

@@ -8,13 +8,6 @@ order: 13
 
 # Browser Support & Polyfills
 
-ReScript compiles to JavaScript **ES5**, with the exception of optionally allowing to compile to ES6's module import & export.
+ReScript compiles to modern JavaScript (ES6+ by default). The generated output targets contemporary browsers and current versions of Node.js, so polyfills are generally not needed.
 
-For [old browsers](https://caniuse.com/#search=typed%20array), you also need to polyfill TypedArray. The following standard library functions require it:
-
-- `Int64.float_of_bits`
-- `Int64.bits_of_float`
-- `Int32.float_of_bits`
-- `Int32.bits_of_float`
-
-If you don't use these functions, you're fine. Otherwise, it'll be a runtime failure.
+If you need to support very old browsers that lack ES6+ features, use your bundler's transpilation and polyfill capabilities (for example, Babel or SWC via Webpack, Vite, or esbuild) to downlevel the output as needed.

markdown-pages/docs/manual/build-configuration.mdx

@@ -81,15 +81,17 @@ Here, the file `src/MyMainModule.res` is exposed to outside consumers, while all
 }
 ```
 
-## bs-dependencies, bs-dev-dependencies
+## dependencies, dev-dependencies
 
 List of ReScript dependencies. Just like `package.json`'s dependencies, they'll be searched in `node_modules`.
 
-Note that only sources marked with `"type":"dev"` will be able to resolve modules from `bs-dev-dependencies`.
+Note that only sources marked with `"type":"dev"` will be able to resolve modules from `dev-dependencies`.
+
+> The legacy keys `bs-dependencies` and `bs-dev-dependencies` are still accepted but deprecated.
 
 ## external-stdlib
 
-**Since 9.0**: This setting allows depending on an externally built stdlib package (instead of a locally built stdlib runtime). Useful for shipping packages that are only consumed in JS or TS without any dependencies to the ReScript development toolchain.
+This setting allows depending on an externally built stdlib package (instead of a locally built stdlib runtime). Useful for shipping packages that are only consumed in JS or TS without any dependencies to the ReScript development toolchain.
 
 More details can be found on our [external stdlib](./build-external-stdlib.mdx) page.
 
@@ -155,7 +157,7 @@ This configuration only applies to you, when you develop the project. When the p
 
 ## suffix
 
-**Since 11.0**: The suffix can now be freely chosen. However, we still suggest you stick to the convention and use
+The suffix can be freely chosen. However, we still suggest you stick to the convention and use
 one of the following:
 
 - `".js`
@@ -190,12 +192,14 @@ Turn off warning `44` and `102` (polymorphic comparison). Turn warning `5` (part
 
 The warning numbers are shown in the build output when they're triggered. See [Warning Numbers](./warning-numbers.mdx) for the complete list.
 
-## bsc-flags
+## compiler-flags
 
 Extra flags to pass to the compiler. For advanced usages.
 
 - `-open ABC` opens the module `ABC` for each file in the project. `ABC` can either be a dependency, namespaced project or local module of the current project.
 
+> The legacy key `bsc-flags` is still accepted but deprecated.
+
 ## gentypeconfig
 
 To enable genType, set `"gentypeconfig"` at top level in the project's `rescript.json`.

markdown-pages/docs/manual/build-external-stdlib.mdx

@@ -9,34 +9,31 @@ order: 4
 
 # External Stdlib
 
-**Since 9.0**
-
-Your ReScript project depends on the `rescript` package as a [`devDependency`](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file), which includes our compiler, build system and runtime like `Belt`. However, you had to move it to `dependency` in `package.json` if you publish your code:
+Your ReScript project depends on the `rescript` package as a [`devDependency`](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file), which includes the compiler, build system, and runtime. However, you may need to move it to `dependency` in `package.json` if you publish your code:
 
 - To Docker or other low-storage deployment devices.
 - For pure JS/TS consumers who probably won't install `rescript` in their own project.
 
-In these cases, the size or mere presence of `rescript` can be troublesome, since it includes not just our necessary runtime like `Belt`, but also our compiler and build system.
+In these cases, the size or mere presence of `rescript` can be troublesome, since it includes not just the necessary runtime, but also the compiler and build system.
 
-To solve that, we now publish our runtime as a standalone package at [`@rescript/std`](https://www.npmjs.com/package/@rescript/std), whose versions mirror `rescript`'s. Now you can keep `rescript` as a `devDependency` and have only `@rescript/std` as your runtime `dependency`.
+To solve that, the runtime is published as a standalone package at [`@rescript/runtime`](https://www.npmjs.com/package/@rescript/runtime), whose versions mirror `rescript`'s. You can keep `rescript` as a `devDependency` and have only `@rescript/runtime` as your runtime `dependency`.
 
 **This is an advanced feature**. Please only use it in the aforementioned scenarios. If you already use a JS bundler with dead code elimination, you might not need this feature.
 
 ## Configuration
 
-Say you want to publish a JS-only ReScript 9.0 library. Install the packages like this:
+Say you want to publish a JS-only ReScript library. Install the packages like this:
 
 ```sh
-npm install rescript@11.0.1 --save-dev
-npm install @rescript/std@11.0.1
+npm install rescript --save-dev
+npm install @rescript/runtime
 ```
 
 Then add this to `rescript.json`:
 
 ```json
 {
-  // ...
-  "external-stdlib": "@rescript/std"
+  "external-stdlib": "@rescript/runtime"
 }
 ```
 
@@ -49,14 +46,11 @@ Array.forEach([1, 2, 3], num => Console.log(num))
 ```
 
 ```js
-// Note the require path starting with "@rescript/std".
-var Belt_Array = require("@rescript/std/lib/js/belt_Array.js");
-
-Belt_Array.forEach([1, 2, 3], function (num) {
+[1, 2, 3].forEach(function (num) {
   console.log(num);
 });
 ```
 
 </CodeTab>
 
-**Make sure the version number of `rescript` and `@rescript/std` match in your `package.json`** to avoid running into runtime issues due to mismatching stdlib assumptions.
+**Make sure the version number of `rescript` and `@rescript/runtime` match in your `package.json`** to avoid running into runtime issues due to mismatching stdlib assumptions.

markdown-pages/docs/manual/build-monorepo-setup.mdx

@@ -58,7 +58,7 @@ The root `rescript.json` manages the monorepo by listing its packages.
     "in-source": true
   },
   "suffix": ".res.mjs",
-  "bsc-flags": []
+  "compiler-flags": []
 }
 ```
 

markdown-pages/docs/manual/build-performance.mdx

@@ -68,9 +68,7 @@ The watcher is also just a thin file watcher that calls `rescript.exe`. We don't
 
 ReScript doesn't take whole seconds to run every time. The bulk of the build performance comes from incremental build, aka re-building a previously built project when a few files changed.
 
-In short, thanks to our compiler and the build system's architecture, we're able to **only build what's needed**. E.g. if `MyFile.res` isn't changed, then it's not recompiled. You can roughly emulate such incrementalism in languages like JavaScript, but the degree of correctness is unfortunately low. For example, if you rename or move a JS file, then the watcher might get confused and not pick up the "new" file or fail to clean things up correctly, resulting in you needing to clean your build and restart anew, which defeats the purpose.
-
-Say goodbye to stale build from your JavaScript ecosystem!
+In short, thanks to our compiler and the build system's architecture, we're able to **only build what's needed**. If `MyFile.res` isn't changed, it isn't recompiled. The build system ensures complete correctness -- renaming or moving files is handled automatically, with no stale builds.
 
 ## Speed Up Incremental Build
 

markdown-pages/docs/manual/control-flow.mdx

@@ -10,11 +10,11 @@ order: 14
 
 ReScript supports `if`, `else`, ternary expression (`a ? b : c`), `for` and `while`.
 
-The `switch` pattern has a default case too, just like many other functional languages. Read more about [pattern-matching & destructuring](./pattern-matching-destructuring.mdx). there.
+The `switch` pattern supports a default case. Read more about [pattern-matching & destructuring](./pattern-matching-destructuring.mdx).
 
 ## If-Else & Ternary
 
-Unlike its JavaScript counterpart, ReScript's `if` is an expression; they evaluate to their body's content:
+ReScript's `if` is an expression; it evaluates to its body's content:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
@@ -94,7 +94,7 @@ var message = isMorning ? "Good morning!" : "Hello!";
 
 </CodeTab>
 
-**`if-else` and ternary are much less used** in ReScript than in other languages; [Pattern-matching](./pattern-matching-destructuring.mdx) kills a whole category of code that previously required conditionals.
+`if-else` and ternary are often replaced by [pattern matching](./pattern-matching-destructuring.mdx), which handles a wide range of conditional logic more expressively.
 
 ## For Loops
 

markdown-pages/docs/manual/converting-from-js.mdx

@@ -12,7 +12,7 @@ ReScript offers a unique project conversion methodology which:
 
 - Ensures minimal disruption to your teammates (very important!).
 - Remove the typical friction of verifying conversion's correctness and performance guarantees.
-- Doesn't force you to search for pre-made binding libraries made by others. **ReScript doesn't need the equivalent of TypeScript's `DefinitelyTyped`**.
+- Doesn't require pre-made binding libraries -- you can write bindings directly for any JavaScript API.
 
 ## Step 1: Install ReScript
 

markdown-pages/docs/manual/editor-plugins.mdx

@@ -40,14 +40,14 @@ The code analysis provides extra checks for your ReScript project, such as detec
 ### Configuration
 
 Add a `reanalyze` section to your `rescript.json` to control what the analyzer checks or ignores. You'll get autocomplete for config options in the editor.  
-More details: [reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)
+More details: [reanalyze configuration docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson)
 
 ### Exception analysis
 
 The exception analysis is designed to keep track statically of the exceptions that might be thrown at runtime. It works by issuing warnings and recognizing annotations. Warnings are issued whenever an exception is thrown and not immediately caught. Annotations are used to push warnings from he local point where the exception is thrown, to the outside context: callers of the current function.
 Nested functions need to be annotated separately.
 
-Instructions on how to run the exception analysis using the `-exception` and `-exception-cmt` command-line arguments, or how to add `"analysis": ["exception"]` in `rescript.json` are contained in the [reanalyze config docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson).
+Instructions on how to run the exception analysis using the `-exception` and `-exception-cmt` command-line arguments, or how to add `"analysis": ["exception"]` in `rescript.json` are contained in the [reanalyze configuration docs](https://github.com/rescript-association/reanalyze#configuration-via-bsconfigjson).
 
 Here's an example, where the analysis reports a warning any time an exception is thrown, and not caught:
 
@@ -142,12 +142,11 @@ There is a way to enhance this behavior via configuration, described further dow
 
 ### Dot completion enhancements
 
-In ReScript, using a dot (`.`) normally means "access record field". But, because using `.` to trigger completions is so pervasive in for example JavaScript, we extend `.` to trigger completions in more scenarios than just for record field access.
+In ReScript, using a dot (`.`) normally means "access record field". The editor extends dot (`.`) to trigger completions in more scenarios beyond record field access, providing a more natural completion flow.
 
 This behavior has the following important implications:
 
 - Improves discoverability (E.g. using a `.` will reveal important pipe completions)
-- Enables a more natural completion flow for people used to JavaScript, where dots power more completions naturally
 
 Below is a list of all the scenarios where using dots trigger completion in addition to the normal record field completion.