I've noticed a pattern in our engineering docs and even in Slack: everyone seems to treat Grammarly's underline as an absolute truth. We're performance-obsessed everywhere else, but we're letting a tool make stylistic calls without any critical thought. This creates inconsistency and can even introduce errors in technical writing.
We need to treat Grammarly like any other heuristic-based system—it has a high recall but questionable precision. Here’s a quick training framework I proposed to my team:
**Phase 1: Awareness (The "Why")**
* Run a simple before/after analysis. Take a well-reviewed technical blog post we have and run it through Grammarly. Have the team vote on which suggestions actually degrade clarity or introduce a passive voice where we need directness.
* Highlight that Grammarly's primary model is trained on general web text, not RFCs, commit messages, or API documentation.
**Phase 2: Rule-Setting (The "What to Override")**
* Establish team-wide rules for common, unhelpful suggestions. For us, this includes:
* Ignoring "wordy" flags on necessary technical terminology.
* Rejecting forced synonyms for domain-specific language (e.g., it always wants to change "latency" to "delay").
* Keeping purposeful sentence fragments for emphasis in our internal communications.
* Disabling the "clarity" score for code-adjacent comments.
**Phase 3: Process (The "How")**
* Make "Review Grammarly's edits" a discrete step in our content workflow, right after "run Grammarly."
* For critical external docs, assign a final reviewer specifically to audit the *human* changes made in response to suggestions, not just the content itself.
The goal isn't to ditch the tool—it's great for catching genuine slips. But we have to measure its output. What's your team's false-positive rate? Have you established any override conventions?
ms matters
Exactly. The same mindset we use to question an alert from a noisy monitoring system has to apply here. That "wordy" flag is a false positive 90% of the time in our world.
You're spot on about the training data. It's like using a general-purpose APM to trace a custom, in-house protocol - you'll get nonsense. Grammarly has no context for why "idempotent" or "idempotency" is the correct, non-negotiable term and shouldn't be "simplified."
One rule we added: ignore all passive voice suggestions for post-mortem or incident documentation. Sometimes "the cache was invalidated" is a factual statement, not a weak one.
Open source is the answer
Your framework's focus on the training data mismatch is critical. We enforce a similar principle with infrastructure linting tools; you wouldn't let `terraform validate` dictate business logic, so why let a general prose model dictate technical semantics? I'd add a concrete exercise for Phase 1: deliberately feed it a snippet from an AWS IAM policy description or a Kubernetes manifest comment. The tool will often try to "correct" the deliberate repetition and specific casing that's required for accuracy, which makes the contextual gap viscerally clear to engineers.
Building on your rule-setting phase, we maintain a small, living document of "vetoed suggestions" tied to document types. A rule like "ignore all conciseness alerts in architecture decision records" prevents the tool from stripping out necessary nuance. The key is treating these overrides as a form of configuration management, versioned and reviewed, not just ad-hoc preferences.
infrastructure is code