Skip to content

docs: edit some docs to adjust tone #1237

Draft
jderochervlk wants to merge 6 commits intomasterfrom
vlk/docs-editing
Draft

docs: edit some docs to adjust tone #1237
jderochervlk wants to merge 6 commits intomasterfrom
vlk/docs-editing

Conversation

@jderochervlk
Copy link
Copy Markdown
Collaborator

@jderochervlk jderochervlk commented Apr 7, 2026

These documentation edits were generated by AI with the following prompts:

  • Remove comparisons to other languages (especially JavaScript)
  • Remove deprecated references
  • Ensure the language manual doesn't read like a step-by-step guide
  • Adjust the tone to be less casual

What changed

Overview page rewritten (overview.mdx): The "Comparison to JS" two-column table format (JavaScript | ReScript) was replaced with a standalone syntax reference. Each section now describes ReScript on its own terms rather than defining it relative to JavaScript.

Removed deprecated pages:

  • browser-support-polyfills.mdx -- outdated ES5/TypedArray polyfill guidance
  • build-external-stdlib.mdx -- the external-stdlib / @rescript/std documentation
  • Corresponding path entries removed from Path.res

Deprecated config keys updated (build-configuration.mdx, build-monorepo-setup.mdx):

  • bs-dependencies / bs-dev-dependencies renamed to dependencies / dev-dependencies (with a note that legacy keys are still accepted)
  • bsc-flags renamed to compiler-flags (with the same deprecation note)
  • external-stdlib section removed

Float operators modernized for v12+ across multiple files:

  • +., -., *., /. replaced with unified operators +, -, *, /
  • primitive-types.mdx updated to document that arithmetic operators work for both int and float

Tone and phrasing adjustments across ~20 files:

  • Removed casual language (=P, =), thankfully, jokes about bosses)
  • Removed "Since X.Y" version markers that dated the documentation
  • Replaced sequential references ("the previous section", "a later section") with direct links
  • Removed comparisons to TypeScript's DefinitelyTyped ecosystem
  • Updated JS output examples to use native methods instead of Belt (Belt_Array.map to .map, Belt_Array.concatMany to native spreads)
  • Changed "JS" abbreviations to "JavaScript" in several places for consistency

Files changed

Category Files
Removed browser-support-polyfills.mdx, build-external-stdlib.mdx
Major rewrite overview.mdx
Config docs build-configuration.mdx, build-monorepo-setup.mdx
Float operator updates primitive-types.mdx, interop-cheatsheet.mdx, type.mdx, generalized-algebraic-data-types.mdx, extension_identity.mdx, language_labeled_argument.mdx, language_open.mdx
Tone/phrasing introduction.mdx, array-and-list.mdx, async-await.mdx, control-flow.mdx, converting-from-js.mdx, editor-plugins.mdx, embed-raw-javascript.mdx, exception.mdx, external.mdx, function.mdx, generate-converters-accessors.mdx, import-from-export-to-js.mdx, interop-with-js-build-systems.mdx, jsx.mdx, libraries.mdx, module.mdx, record.mdx, shared-data-types.mdx, build-performance.mdx

@jderochervlk jderochervlk changed the title Vlk/docs editing docs: edit some docs to adjust tone Apr 7, 2026
@github-actions
Copy link
Copy Markdown

github-actions bot commented Apr 7, 2026

Cloudflare deployment

Deployement ID: 0d7d6b92-e060-4a91-a69f-1a1c36ec367a
Deployment Environment: preview

⛅️ wrangler 4.63.0 (update available 4.81.0)
─────────────────────────────────────────────
✨ Compiled Worker successfully
Uploading... (7647/7654)
Uploading... (7649/7654)
Uploading... (7651/7654)
Uploading... (7654/7654)
✨ Success! Uploaded 7 files (7647 already uploaded) (2.76 sec)

✨ Uploading _redirects
✨ Uploading Functions bundle
🌎 Deploying...
✨ Deployment complete! Take a peek over at https://0d7d6b92.rescript-lang.pages.dev
✨ Deployment alias URL: https://vlk-docs-editing.rescript-lang.pages.dev

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant