docs: edit some docs to adjust tone

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/build-configuration.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-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. 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.
 
 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.
 

markdown-pages/docs/manual/embed-raw-javascript.mdx

@@ -36,7 +36,7 @@ function greet(m) {
 
 The `%%raw` special ReScript call takes your code string and pastes it as-is into the output. **You've now technically written your first ReScript file!**
 
-(The back tick syntax is a multiline string, similar to JavaScript's. Except for us, no escaping is needed inside the string. More on string in a later section.)
+(The backtick syntax is a multiline string. No escaping is needed inside the string.)
 
 While `%%raw` lets you embed top-level raw JS code, `%raw` lets you embed expression-level JS code:
 
@@ -70,7 +70,7 @@ The above code:
 - with the raw JavaScript value of a function declaration,
 - then called that function in ReScript.
 
-If your boss is ever worried that your teammates can't adopt ReScript, just let them keep writing JavaScript inside ReScript files =).
+Existing JavaScript code can live inside ReScript files during migration.
 
 ## Debugger
 
@@ -113,4 +113,4 @@ Embedding raw JS snippets isn't the best way to experience ReScript, though it's
 
 At the end, we get a fully safe, converted ReScript file whose JS output is clean enough that we can confidently assert that no new bug has been introduced during the conversion process.
 
-We have a small guide on this iteration [here](./converting-from-js.mdx). Feel free to peruse it later.
+See the [Converting from JS](./converting-from-js.mdx) guide for a detailed walkthrough.

markdown-pages/docs/manual/exception.mdx

@@ -452,7 +452,7 @@ try {
 
 ## Catch ReScript Exceptions from JS
 
-The previous section is less useful than you think; to let your JS code work with your exception-throwing ReScript code, the latter doesn't actually need to throw a JS exception. ReScript exceptions can be used by JS code!
+To let JavaScript code work with exception-throwing ReScript code, you don't need to throw a JS exception. ReScript exceptions can be used directly from JavaScript.
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 

markdown-pages/docs/manual/external.mdx

@@ -77,9 +77,9 @@ document.location.href = "rescript-lang.org";
 
 </CodeTab>
 
-We've specified `document`'s type as `'a`, aka a placeholder type that's polymorphic. Any value can be passed there, so you're not getting much type safety (except the inferences at various call sites). However, this is excellent for quickly getting started using a JavaScript library in ReScript **without needing the equivalent of a repository of typed bindings** like TypeScript's `DefinitelyTyped` repo.
+We've specified `document`'s type as `'a`, a placeholder type that's polymorphic. Any value can be passed there, so you're not getting much type safety (except the inferences at various call sites). This is useful for quickly getting started with a JavaScript library in ReScript since you can write bindings directly for any API you need.
 
-However, if you want to more rigidly bind to the JavaScript library you want, keep reading the next few interop pages.
+For more rigidly typed bindings, see the other interop pages in this section.
 
 ## Performance & Output Readability
 

markdown-pages/docs/manual/function.mdx

@@ -10,7 +10,7 @@ order: 13
 
 _Cheat sheet for the full function syntax at the end_.
 
-ReScript functions are declared with an arrow and return an expression, just like JS functions. They compile to clean JS functions too.
+ReScript functions are declared with an arrow and return an expression. They compile to clean JavaScript functions.
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
@@ -639,6 +639,6 @@ To annotate a function from the implementation file (`.res`) in your interface f
 let add: (int, int) => int
 ```
 
-The type annotation part is the same as the previous section on With Type Annotation.
+The type annotation syntax is the same as described in [With Type Annotation](#with-type-annotation) above.
 
 **Don't** confuse `let add: myType` with `type add = myType`. When used in `.resi` interface files, the former exports the binding `add` while annotating it as type `myType`. The latter exports the type `add`, whose value is the type `myType`.

markdown-pages/docs/manual/generalized-algebraic-data-types.mdx

@@ -125,9 +125,7 @@ GADTs give us is that the compiler less able to help us with type inference.
 
 ## Varying return type
 
-Sometimes, a function should have a different return type based on what you give it, and GADTs are how we can do this in a type-safe way. We can implement a generic `add` function[^1] that works on both `int` or `float`:
-
-[^1]: In ReScript v12, the built-in operators are already generic, but we use them in this example for simplicity.
+Sometimes, a function should have a different return type based on what you give it, and GADTs are how we can do this in a type-safe way. We can implement a generic `add` function that works on both `int` or `float`:
 
 {/* this example purposefully has an error so it is not marked as an example */}
 
@@ -137,7 +135,7 @@ type rec number<_> = Int(int): number<int> | Float(float): number<float>
 let add = (type a, x: number<a>, y: number<a>): a =>
   switch (x, y) {
   | (Int(x), Int(y)) => x + y
-  | (Float(x), Float(y)) => x +. y
+  | (Float(x), Float(y)) => x + y
   }
 
 let foo = add(Int(1), Int(2))
@@ -199,7 +197,7 @@ and num = Num(numTy<'a>, 'a): num
 and num_array = Narray(numTy<'a>, array<'a>): num_array
 
 let addInt = (x, y) => x + y
-let addFloat = (x, y) => x +. y
+let addFloat = (x: float, y: float) => x + y
 
 let sum = (Narray(witness, array)) => {
   switch witness {

markdown-pages/docs/manual/generate-converters-accessors.mdx

@@ -111,7 +111,7 @@ var pets = [
   },
 ];
 
-console.log(Belt_Array.map(pets, name).join("&"));
+console.log(pets.map(name).join("&"));
 ```
 
 </CodeTab>

markdown-pages/docs/manual/import-from-export-to-js.mdx

@@ -12,7 +12,7 @@ You've seen how ReScript's idiomatic [Import & Export](./import-export.mdx) work
 
 If you're looking for react-specific interop guidance, check out the [React JS Interop guide](../react/import-export-reactjs.mdx).
 
-**Note**: due to JS ecosystem's module compatibility issues, our advice of keeping your ReScript file's compiled JS output open in a tab applies here **more than ever**, as you don't want to subtly output the wrong JS module import/export code, on top of having to deal with Babel/Webpack/Jest/Node's CommonJS \<-> JavaScript module compatibility shims.
+**Tip**: keep your compiled JS output open in a tab to verify the generated import/export code.
 
 In short: **make sure your bindings below output what you'd have manually written in JS**.
 

markdown-pages/docs/manual/interop-cheatsheet.mdx

@@ -271,7 +271,7 @@ Final escape hatch converter. Do not abuse.
 ```res example
 external convertToFloat: int => float = "%identity"
 let age = 10
-let gpa = 2.1 +. convertToFloat(age)
+let gpa = 2.1 + convertToFloat(age)
 ```
 
 ```js