docs: edit some docs to adjust tone (#1237)

* docs: edit some docs to adjust tone

* Remove external-stdlib documentation

* docs: remove double dashes and clean up AI language

* remove polyfill page

* docs: replace deprecated float operators with unified operators for v12+

* fix: broken link to deleted external-stdlib page and addFloat type inference

* docs: restore removed version markers in build config (#1249)

* Apply suggestion from @jderochervlk

* Apply suggestion from @jderochervlk

* remove dead link

Author: jderochervlk

markdown-pages/blog/release-9-0.mdx

@@ -34,7 +34,7 @@ Our compiler comes with a set of stdlib modules (such as `Belt`, `Pervasives`, e
 
 In previous versions, users couldn't ship their compiled JS code without defining a `package.json` dependency on `bs-platform`. Whenever a ReScript developer wanted to publish a package just for pure JS consumption / lean container deployment, they were required to use a bundler to bundle up their library / stdlib code, which made things way more complex and harder to understand.
 
-To fix this problem, we introduced an `external-stdlib` configuration that allows specifying a pre-compiled stdlib npm package (`@rescript/std`). More details on how to use that feature can be found in our [External Stdlib](../docs/manual/build-external-stdlib.mdx) documentation.
+To fix this problem, we introduced an `external-stdlib` configuration that allows specifying a pre-compiled stdlib npm package (`@rescript/std`).
 
 ### Less Bundle Bloat when Adding ReScript
 

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"]}>
 
@@ -84,7 +84,7 @@ myArray[0] = "bye";
 
 **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 +96,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

@@ -81,17 +81,13 @@ 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`.
 
-## 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.
-
-More details can be found on our [external stdlib](./build-external-stdlib.mdx) page.
+> The legacy keys `bs-dependencies` and `bs-dev-dependencies` are still accepted but deprecated.
 
 ## js-post-build
 
@@ -155,7 +151,8 @@ 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
+**Since 11.0**: The suffix can be freely chosen. However, we still suggest you stick to the convention and use
+
 one of the following:
 
 - `".js`
@@ -190,12 +187,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-configuration.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-external-stdlib.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. Renaming or moving files is handled automatically, with no stale builds.
 
 ## Speed Up Incremental Build
 

markdown-pages/docs/manual/build-monorepo-setup.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/build-performance.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