How to Set Up a Restricted Words List for Product Docs Comments

Setting up a restricted words list for product documentation requires balancing signal against disruption: holding hostile language and promotional spam while keeping the queue open for error traces, code snippets, and bug reports. This walkthrough explains how to set up restricted words list for product docs comments so your technical team can stop triaging junk without silently discarding legitimate developer feedback.

Why a docs comment section needs its own blocklist

Documentation comments bear little resemblance to standard blog commentary. Readers arrive at developer documentation, API references, and configuration guides when their workflow is already broken. In that context, legitimate contributions routinely include raw stack traces, terminal dumps, syntax error strings, and frank comparisons to competitor platforms. When a frustrated engineer writes a comment containing an unhandled exception or venting about an API breaking change, a naive filter often blocks the technical data while letting evasive promotional links slip straight through.

The cost of an inaccurate blocklist on technical documentation is heavily asymmetric. If an over-aggressive rule triggers a false reject on a docs page, you lose an authentic bug report, an unindexed edge case, or a missing step in your setup tutorial. The reader rarely opens a support ticket to report that their documentation comment was suppressed; they simply abandon the tool or file a public complaint. Conversely, a false hold costs a technical moderator mere seconds to review and release. For anyone evaluating comment filtering for technical docs, protecting genuine developer contributions must take priority over ruthless automatic suppression.

A well-tuned blocklist accomplishes two concrete operational jobs:

• Preserves page utility for other readers: Unchecked hostility, link spam, and impersonation degrade the practical value of documentation. According to the definition of usability provided by the NIST Computer Security Resource Center, usability encompasses the effectiveness, efficiency, and satisfaction with which specified users achieve specified goals in particular environments. A hostile or spam-riddled thread actively degrades that efficiency.
• Protects moderator throughput: Without deterministic pre-filtering, documentation maintainers waste hours triaging the exact same commercial spam payloads, link-farm schemes, and abusive slurs day after day.

This operational walkthrough addresses teams managing documentation communities that already have steady comment volume. If your moderation queue has become an unmanageable daily chore, the following process establishes deterministic moderation rules for documentation that keep your queue under control.

What EchoThread's restricted-words list actually does

To implement effective filtering, you need to understand how the underlying engine evaluates submitted content. EchoThread lets a site owner keep a restricted-words list of up to 2,000 entries, matched case-insensitively against the comment body and the author's display name, where "*" matches a run of non-space characters. The owner chooses once for the whole EchoThread restricted-words list whether a match holds the comment for review or rejects it; a display-name match always holds rather than rejects.

Processing order is critical when diagnosing why a comment landed in a particular state. EchoThread runs restricted-words matching before the spam classifier, so a comment the rule decides never reaches it, and the EchoThread moderation queue labels the decision as the owner's own rule and shows the text that matched. If an incoming comment contains a restricted string configured to hold, it bypasses downstream heuristics and lands directly in the review queue with an explicit audit tag identifying which entry fired.

Access control and tier availability remain straightforward. Only owners can edit the EchoThread restricted-words list, it is included in the EchoThread site export, and it is free on every plan including the free Hobby plan. For engineering teams evaluating architectural fit, EchoThread is a proprietary, hosted SaaS commenting platform; it is not open source. Only its integrations are: the EchoThread MCP server (@echothread/mcp) and n8n node (@echothread/n8n-nodes-echothread) are MIT-licensed on GitHub. You can review all operational thresholds and seat limits directly on the EchoThread pricing page and consult syntax details within the EchoThread documentation.

Decide hold or reject before you write a single entry

Before adding entries to your blocklist, you must establish whether your global policy will hold matched comments for human review or reject them outright. On technical documentation, hold is the correct default setting. A held comment remains visible to moderators in the dashboard, where a single click can publish a false positive. A rejected comment vanishes immediately, cutting off valuable user feedback and leaving the reader with no indication why their submission failed.

Outright rejection is defensible only when you maintain a narrow list of unequivocal abuse: targeted slurs, verified link-farm redirectors, and explicit payment fraud keywords. In those situations, there is no plausible technical context where the phrase could appear in a constructive API discussion. However, because EchoThread applies the hold-or-reject choice globally across the entire restricted-words list, configuring the list to reject requires absolute certainty that none of your entries collide with technical vocabulary.

Apply this decision rule across your documentation team: If you can formulate even one plausible scenario where a legitimate user troubleshooting your software might type that string, the list must remain set to hold. If your list contains a mix of nuisance terms and severe abuse, keep the global action on hold. Reviewing a handful of nuisance items each morning takes trivial effort compared to losing an authentic customer bug report.

Note how display names interact with this policy. In EchoThread, an entry match against a commenter's display name always defaults to a hold, even if the primary list action is set to reject. This safeguards community members whose valid developer handles, corporate usernames, or abbreviations happen to share a substring with an entry on your blocklist.

Build the list in four passes

Do not import a generic 5,000-word internet blocklist into technical documentation. Pre-packaged lists inevitably include technical jargon, biological references, and common terms that break developer discussions. Instead, construct your list through four systematic passes.

Pass 1: Slurs and harassment terms

Keep this pass short, focused, and curated. Include explicit hate speech, severe harassment phrases, and unambiguous epithets. Because these terms have zero legitimate engineering utility, this category justifies high-confidence enforcement. Do not attempt to enumerate every possible variation or phonetic misspelling; focus on the primary stems that immediately compromise the professional standard of your documentation.

Pass 2: Spam payloads and link schemes

Examine the spam patterns that regularly bypass general spam scoring. This typically involves gambling promotions, pharmaceutical dropshipping, cryptocurrency giveaway patterns, Telegram contact solicitations, and link-shortener redirects. Focus on operational phrases rather than isolated nouns. For example, targeting phrases like join * channel or whatsapp * crypto catches promotional schemes without blocking genuine references to public communication protocols.

Pass 3: Competitor mentions and product comparisons

Decide deliberately how your team treats competitor names. In developer documentation, readers regularly ask: "How does this auth header compare to Okta?" or "Does this SDK migrate cleanly from Stripe?" Blocking competitor names outright alienates technical evaluators who need clear integration comparisons. If competitor marketing spam is a recurring problem, place those brand names on the list while ensuring your global setting is set to hold. This lets your engineering or developer relations team review the context, approve authentic architectural questions, and reject blatant promotional plugs.

Pass 4: Wildcard patterns and stem matching

Use the asterisk wildcard (*) to match non-space characters rather than writing dozens of manual permutations. For instance, rather than adding multiple variants of a link-spam phrase, you can craft a targeted wildcard entry that bridges arbitrary punctuation or obfuscation characters. Maintain internal release notes explaining why each wildcard pattern was introduced. Without documentation, future maintainers may delete a cryptic wildcard entry, immediately reopening the queue to an old spam vector.

Write entries that match what you mean

EchoThread matches restricted entries case-insensitively across both the comment body and the author's display name. You do not need to enter separate capitalized, lowercase, or title-case variations. However, you must account for word boundaries and string containment.

A short, bare word matches anywhere the exact sequence appears if not bounded properly. If you enter a three-letter fragment, you risk matching longer, legitimate English and technical terms. When crafting patterns, prefer the longest unique stem that isolates the abuse. If you are catching evasion patterns, pair the stem with an asterisk to span variable suffixes without capturing unrelated words.

Consider these concrete examples for a documentation setting:

• Targeted phrase: t.me/* holds Telegram promotional channels frequently pasted into API threads, without blocking technical references to domain names ending in valid top-level domains.
• Unambiguous promotional pattern: whatsapp * +* catches unsolicited support diversion scams that attempt to pull frustrated developers off your official docs into external chat platforms.
• Competitor audit: competitorproduct configured on a hold-enabled list flags the comment for developer relations review so your team can verify technical accuracy before publication.

Before committing new entries to your live documentation, run a three-point test against your historical queue. Identify one historical comment that should trigger the rule, one authentic technical comment that must pass untouched, and one borderline comment containing complex code formatting. Testing candidate patterns against historical data prevents unexpected queue surges.

While EchoThread provides capacity for up to 2,000 entries on all tiers, technical documentation rarely requires more than 100 to 200 carefully tuned rules. A compact, auditable list is vastly easier to maintain than an unwieldy collection of conflicting strings.

The docs-specific edge cases that break a blocklist

Technical documentation presents parsing challenges rarely encountered on standard publishing platforms. When implementing comment moderation queue rules for product documentation, watch for four distinct edge cases.

1. Error strings, status codes, and HTTP headers

Developers routinely paste raw terminal output containing status codes, protocol errors, and debugging identifiers. Standard HTTP headers defined under the IETF RFC 9110 HTTP Semantics specification—such as Proxy-Authenticate, Host, or custom vendor headers—frequently appear in integration queries. If your blocklist includes common substrings like proxy or host to combat spam domains, you will inadvertently intercept standard network debugging logs.

2. Code blocks, JSON payloads, and quoted logs

Commenters frequently wrap error messages, database dumps, and configuration payloads inside code blocks. A user troubleshooting an authentication failure might paste an identity provider payload containing token fields, validation errors, or security warnings. If your restricted list contains security-related terms (such as exploit, vulnerability, or payload), technical discussions regarding defensive configurations will be trapped in the review queue.

3. Multilingual comments and homoglyph collisions

If your documentation serves international teams, internationalization introduces subtle collisions. A word that represents an offensive English slang term may be a completely benign pronoun, noun, or verb in French, Italian, or German. Additionally, automated spam bots often substitute Cyrillic or Greek characters for Latin glyphs to bypass rudimentary string filters. While the Unicode Consortium Technical Report #39 on Security Mechanisms details standard practices for detecting mixed-script confusable characters, a simple text-matching list treats these homoglyphs as distinct characters. Using concise wildcard stems rather than attempting to enumerate mixed-alphabet substitutions prevents unnecessary list bloat.

4. Product names that collide with common vocabulary

Modern software tools frequently use common dictionary nouns for libraries, utilities, and CLI commands. Before adding any word to your documentation blocklist, paste it into your internal docs search bar. If the term yields dozens of hits across your own tutorials, API guides, and code samples, adding it to your restricted list will inevitably catch genuine developers quoting your own documentation back to you.

Run the list as a weekly procedure, not a one-off setup

A restricted-words list is not a set-and-forget safeguard. It is an operational tool that requires recurring calibration. Incorporate it into your team's existing triage cadence alongside your comment moderation workflow for product teams.

1. Conduct a weekly queue audit: Every Monday, review comments held by owner-authored rules. Inspect the specific text that triggered the hold. If a single entry accounts for multiple approved comments, that entry is generating false positives and needs refinement or removal.
2. Coordinate with documentation releases: Whenever your engineering team launches new API endpoints, renames CLI commands, or introduces new error codes, verify that the updated naming conventions do not collide with your active blocklist.
3. Combine with complementary moderation layers: Do not force your restricted-words list to handle problems better solved by other controls. EchoThread's per-site commenter ban and trust are free on every EchoThread plan; an EchoThread ban applies to that one site and never platform-wide. If an individual repeatedly posts off-topic rants, ban that commenter per-site rather than adding their idiosyncratic vocabulary to your global list. Similarly, trust verified contributors to let their technical questions publish instantly.
4. Close stale documentation threads: Outdated documentation pages attract low-quality spam and obsolete questions that confuse readers. EchoThread can close threads to new comments 30, 60, 90, 180 or 365 days after creation; on a closed EchoThread thread, existing comments stay visible and readable. Automating thread closure on older documentation versions keeps your active moderation queue focused on current software releases.

For teams with high documentation traffic, resolving holds quickly is essential. On EchoThread Starter and above, EchoThread emails the site owner and moderators each comment awaiting review with Approve, Reject and Spam links that need no login. This allows technical writers, support leads, and documentation maintainers to clear legitimate developer questions directly from an inbox notification without logging into the main dashboard.

Measure whether the list is working

To determine if your documentation moderation rules remain healthy over time, track two core operational metrics:

Every quarter, export your site settings and audit the top five entries responsible for the highest hold counts. The entry triggering the most holds is statistically the most likely candidate for false positives. Keeping your exported list in version control provides a simple rollback mechanism if an over-broad regex or wildcard disrupts queue operations after a docs deployment.

Conclusion: a short list you trust beats a long list you don't

Creating an effective restricted-words list for documentation is not an exercise in compiling an encyclopedic dictionary of human misconduct. Maintaining an auditable set of fifty well-targeted entries that you understand and review regularly is far more reliable than managing thousands of blind entries imported from third-party repositories.

Keep your global enforcement set to hold, build out your rules using the four-pass framework outlined above, and establish a recurring Monday routine to clear holds and tune colliding entries. When combined with targeted commenter controls and thread closure on legacy guides, deterministic keyword rules protect your engineering documentation while keeping your queue fast and manageable.

Frequently Asked Questions

How many entries can a restricted-words list hold in EchoThread?

EchoThread lets a site owner keep a restricted-words list of up to 2,000 entries. Entries are matched case-insensitively against the comment body and the author's display name, and the asterisk symbol (*) functions as a wildcard matching any run of non-space characters.

Should a restricted-words match hold a comment for review or reject it outright?

For technical documentation, a restricted-words match should almost often be configured to hold comments for review. Documentation readers frequently paste complex error traces, logs, and competitor comparisons that can inadvertently trigger keyword filters. A held comment remains recoverable in your moderation dashboard, whereas an outright rejection permanently drops authentic bug reports and user feedback.

Will a restricted-words list block legitimate bug reports on a docs page?

A naive or overly broad blocklist will easily block bug reports if it includes common substrings, standard HTTP status phrases, or technical terms like "proxy", "host", or "payload". To prevent blocking legitimate technical contributions, construct your list using specific multi-word stems, test each entry against historical queue data, and keep the list action configured to hold rather than reject.

Does the restricted-words list run before or after spam filtering?

In EchoThread, restricted-words matching runs before the spam classifier. When an incoming comment matches an entry on the restricted-words list, the rule executes immediately, and the submission bypasses downstream spam scoring. The moderation queue explicitly labels the item as an owner rule and highlights the exact matching text for review.

Can moderators edit the restricted-words list, or only the site owner?

Only the site owner can edit the restricted-words list in EchoThread. While moderators can review, approve, reject, and mark comments as spam in the daily queue, configuration of global site rules, export settings, and blocklist entries is restricted exclusively to the site owner account.

Start with the free EchoThread Hobby plan, add your first twenty restricted-word entries as holds, and run the list against one week of real docs comments before you widen it — then check EchoThread pricing when you need email approvals, Slack alerts or more sites.