Pour a JavaScript README through Grammarly and watch what happens. The checker flags npm as a missing capital, Redis as a probable typo, OAuth as a misspelling of "oath," and bool as a fragment. It underlines a fenced code block as "no clear subject." It suggests rewriting the line "the function returns a Promise that resolves to undefined" because the tool does not know what a Promise is and thinks "undefined" is a missing article.
Most technical writers learn to dismiss the noise within an hour. But the noise hides legitimate flags, and after a while the entire tool becomes background hum. This is a look at why grammar checkers misfire on technical jargon, what the better ones do about it, and how to set up a workflow that does not punish you for writing about software.
What the Checker Sees in a Code-Heavy Draft
A grammar checker is a tokenizer plus a rule engine. It splits the text into words, looks each one up in a dictionary, and runs a set of grammatical rules over the resulting parse. Words that are not in the dictionary get flagged as spelling errors. Sentences that do not parse cleanly get flagged as fragments or run-ons. Names that the dictionary contains in lowercase form get flagged as capitalization errors when they appear capitalized, and vice versa.
Technical writing breaks all of these assumptions.
The first problem is product names. kubectl, npm, eslint, jq, awk, psql, and a hundred others are lowercase on purpose. The checker either flags them as needing capitalization or, worse, autocorrects them to a homophone like "knpm" or "nlsh." The fix is to add each one to the personal dictionary, which the checker eventually accepts but which has to be done per project per checker.
The second problem is acronyms. OAuth looks to the checker like "oath" with a misplaced capital. HTTP looks fine until you write HTTPS and the checker decides it should be HTTPs. IPv4 and IPv6 get flagged for the mixed case. The checker is applying English capitalization rules to terms that follow domain-specific conventions, and it has no signal that lets it switch.
The third problem is fenced code. A grammar checker that does not understand Markdown will read the contents of a code block as prose. It flags the missing periods at the end of statements, the unusual whitespace around operators, the camelCase variable names. A checker that does understand Markdown skips the fenced content correctly. Most of the editor plugins now do this; some of the CLI tools and many of the web tools still do not.
The fourth problem is inline code spans. The single-backtick inline code syntax is supported by some checkers and not by others. Sentences like "the useEffect hook runs after render" parse cleanly in human reading and incorrectly in tools that strip the backticks before tokenizing. The result is suggestions to rewrite the sentence around the "missing word."
The fifth problem is sentence fragments in list items. Technical documentation uses bulleted lists with fragmentary entries on purpose. "Idempotent on retry" is a legitimate entry in a function-properties list, not a broken sentence. A checker that flags every fragment generates dozens of false positives per page.
Why the Tools Do Not Just Fix This
The honest answer is that fixing it well is harder than it sounds. The checker has to understand the document format, the project's term dictionary, the genre conventions, and the syntactic role of each fenced or inlined element. That requires a richer model of the text than the regex-plus-rules engine most tools still use.
The slow improvement has been happening. The LanguageTool team added Markdown awareness and a much larger technical dictionary in their open-source builds over the last two years. Microsoft Editor in Visual Studio Code now respects fenced code in Markdown files when run as the in-editor checker. Grammarly added a "technical writing" goal that loosens several rules and accepts more jargon, though the underlying tokenizer still misfires on uncommon project names.
The web-based AI Grammar Checker at EvvyTools handles fenced code blocks and inline code spans correctly, and the dictionary covers most common open-source project names without manual additions. It is not perfect, but it is closer to "useful out of the box for a developer-facing draft" than most of the older tools.
The Three Things That Help Right Now
The fixes are not exotic. They just require setup time.
The first is to build a project glossary file. Every product, library, command, and acronym that appears more than once in your docs gets added to a single dictionary file checked into the repo. The checker reads from that file at startup. Vale supports this natively; LanguageTool reads a .languagetool.cfg or per-paragraph hint files; most editor plugins have a "personal dictionary" that can be pointed at a shared file. The initial pass takes an hour. The ongoing maintenance is a minute per week.
The second is to configure the tool to skip fenced and inline code. Vale does this by default for Markdown. LanguageTool does it if you set the input format to markdown. The CLI flags vary; the documentation for each tool is the right place to check. If you write a lot of technical Markdown, do not run a checker that cannot do this.
The third is to disable the categories that generate the most noise on technical text. The "weak verb" category, the "sentence length" category, and the "passive voice" category each produce ten times more false positives than true positives on a typical API reference page. Turning them off does not lose anything important. For more on why passive voice in particular deserves to be off for technical genres, see the longer piece on why grammar checkers flag passive voice even when it is the right choice.
A Workflow That Holds Up on Developer-Facing Docs
A workflow that actually works has four layers.
Layer one is the editor plugin. The author drafts inside an editor that runs the grammar checker live. This catches typos and basic grammar errors at draft time, when the fix is immediate.
Layer two is the project glossary. The shared dictionary lives in the repo and is loaded by every layer. Adding a new term takes seconds. The checker stops flagging it for everyone.
Layer three is the CI step. On every PR that touches docs, a CI job runs the checker against the changed files only, fails on the blocking categories, and surfaces the rest as advisory comments. The blocking categories should be subject-verb agreement, homophone confusion, comma splices, and repeated words. Everything else stays advisory.
Layer four is the periodic full pass. Once a quarter, run the checker against the whole docs tree and look at the trends. Errors that show up in many files are usually a sign that the project glossary is missing terms. Add them and rerun.
For a one-off draft pass without the CI infrastructure, the free grammar checker at covers the same ground for paste-in drafts, which is useful for blog posts and release notes that do not live in the repo.
What the Checkers Will Eventually Do Better
The next generation of grammar checkers is being trained on much larger corpora of technical writing. The 2026 versions of LanguageTool and the AI Grammar Checker both ship with dictionaries that include the top 5,000 open-source project names without manual configuration. The dictionaries are still missing the names of your internal services, your custom command-line tools, and your own product. Those still need the glossary file.
The genre-detection problem is harder. A tool that could tell that the current document is a methods section, a recipe, a security postmortem, or a marketing landing page would adjust its rule set accordingly. That capability is being prototyped by several vendors but is not yet reliable enough to ship as a default. Until it does, manual rule toggles are the best a writer can do.
For the broader question of how to read grammar checker suggestions in any genre, the longer guide on why grammar checkers flag passive voice even when it is the right choice covers the underlying logic. The short summary is that a grammar checker is a recall device that surfaces every candidate, and the writer's job is to decide which candidates matter for the genre at hand.
For more drafting helpers, the EvvyTools writing tools directory collects related options. The Vale documentation and the LanguageTool homepage are the right places to compare CLI-driven tooling against the web-based and editor-plugin options.
Top comments (0)