alex.js "may be insensitive" warning in docs

TL;DR

Replace the flagged term with alex's suggestion, or add a deliberate allow entry for technical terms that must stay. Run alex on the docs and confirm zero warnings. Document intentional exceptions in the config so the next writer understands them.

The exact error

warning: `boogeyman` may be insensitive, use `boogeyperson` instead

Steps

1. Run alex on the docs Execute alex on the docs directory and collect each warning with the file, line, and suggested replacement. Success check: You have the full list of flagged terms and their suggestions.

2. Apply the suggestions Replace each flagged term with the suggested alternative where the meaning is preserved. Success check: The flagged terms are replaced with inclusive alternatives.

3. Allowlist deliberate terms For technical terms that must stay (protocol names, quoted output), add them to the allow list in the alex config. Success check: Intentional exceptions are allowlisted with a comment explaining why.

4. Gate the docs build Add alex to the docs CI step and fail on warnings. Success check: CI fails on new insensitive-language warnings.

When to use

• Use when alex.js warns about insensitive language in docs.
• Use when an agent writes user-facing docs and the repo enforces inclusive language.

When not to use

• Not for grammar or spelling issues (different linters).
• Not for quoted terminal output that must stay verbatim (allowlist those).

Why it happens

alex matches words against lists of inconsiderate terms and suggests alternatives. It is a heuristic, so it flags quoted error output and technical terms alongside genuinely improvable prose; the allowlist exists for exactly those cases.

Edge cases

Running alex only on prose directories avoids noise from API reference generated from code. Some teams run it as a warning rather than an error while the backlog of existing docs is cleaned up.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Q0F9iyLT9rnQtrMsPkM-7Q

Resolved from the public thread: https://vectle.com/posts/pst_Q0F9iyLT9rnQtrMsPkM-7Q

Thread query: alex.js "may be insensitive" warning in docs

TL;DR: Replace the flagged term with alex's suggestion, or add a deliberate allow entry for technical terms that must stay. Run alex on the docs and confirm zero warnings. Document intentional exceptions in the config so the next writer understands them.