Technical writers get pulled in two directions on every doc they write. Simplify too much and expert users feel talked down to, skipping past explanations they don't need. Write at a naturally technical register and newcomers bounce off the second paragraph, unable to follow a sentence that assumes context they don't have yet.
Step One: Decide Who the Doc Is Actually For
Before adjusting a single sentence, name the audience specifically. "Developers" is too broad, a senior engineer integrating your API and a bootcamp graduate trying their first webhook need genuinely different explanations, not just different vocabulary. Getting Started guides should assume almost nothing. Reference documentation can assume the reader already knows the basics and just needs precise, dense facts fast.
Writing the audience down explicitly, even just a sentence in your own notes, keeps you from unconsciously drifting toward whichever register you personally find comfortable, which is rarely the same register your least experienced reader needs.
Step Two: Draft Without Worrying About Reading Level Yet
Write the first pass focused entirely on accuracy and completeness. Trying to simplify language while you're still figuring out what needs to be said produces worse documentation than getting the technical content right first and adjusting the language in a dedicated second pass.
This separation matters because reading-level adjustments and technical-accuracy adjustments pull your attention in different directions, and doing both at once means neither gets full attention.
Step Three: Measure the Actual Reading Level
Readability scores, built on formulas that weigh sentence length and syllable count, give you an objective number instead of a gut feeling about whether a doc "reads easy." A Getting Started guide sitting at a graduate-reading-level score is a signal worth acting on, even if every sentence felt clear while you were writing it.
EvvyTools' Reading Level Analyzer scores pasted text against standard readability formulas, flagging exactly where a doc has drifted denser than its audience can comfortably follow.
Step Four: Shorten Sentences Before You Simplify Vocabulary
The single highest-leverage fix for a high reading-level score is almost always sentence length, not word choice. A twenty-eight word sentence with three subordinate clauses is hard to parse regardless of how simple its individual words are. Breaking that sentence into two or three shorter ones usually drops the score more than swapping any single technical term ever would.
Keep genuinely necessary technical terms. The goal isn't dumbing down content, it's removing unnecessary friction, mainly sentence structure, that has nothing to do with the actual difficulty of the concept being explained.
Step Five: Handle Jargon Deliberately, Not by Avoiding It
Some technical vocabulary is unavoidable and even helpful, a precise term used consistently is easier to follow than three different vague paraphrases of the same idea. The Plain Language guidelines used across U.S. federal agencies make this exact distinction: plain language isn't the absence of specialized terms, it's using them deliberately, defining them once, and staying consistent afterward.
Define a term clearly the first time it appears, then use that exact term every time afterward rather than rotating through synonyms that force the reader to re-verify you're still talking about the same thing.
Step Six: Re-Check After Every Substantial Edit
Reading level shifts every time you add a clarifying clause or a caveat, which good technical writers do constantly as they catch edge cases. Re-running the readability check after a substantial revision pass, not just once at the very start, catches score creep that happens gradually and invisibly across a long editing session.
Step Seven: Test With an Actual Reader From the Target Audience
No formula fully substitutes for watching a real newcomer try to follow your Getting Started guide. Readability scores catch sentence-level friction; they don't catch a missing prerequisite step or an assumption that a reader has already set up something they haven't. Pair the score with at least one real read-through from someone at the audience level you named in step one.
Applying This Beyond Documentation
The same discipline applies to blog posts, onboarding emails, and even error messages, anywhere the reader's patience for parsing dense language is limited. Communities like freeCodeCamp have built entire teaching philosophies around meeting learners at their actual reading level rather than the level the writer happens to think in.
It's worth applying the same rigor to a piece's headline as its body, since a dense headline loses readers before the readability of the body ever gets tested. EvvyTools' guide to what makes a headline score well walks through the same kind of clarity check applied to the first line instead of the paragraphs underneath it.
Code Comments Deserve the Same Scrutiny
Reading level isn't just a prose problem. A code comment explaining a tricky piece of logic is documentation too, and one written in the same dense, jargon-heavy register the author thinks in can be just as opaque to the next engineer as an overly technical paragraph is to a new user. The audience for a comment is a future maintainer who may not share the original author's full context, which is functionally the same challenge as writing a Getting Started guide for a reader who doesn't yet know your product.
Teams that write style guidelines for commit messages and code comments, a practice documented in various forms across projects hosted on GitHub, often converge on the same advice technical writers give for prose: shorter sentences, one idea per comment, and defining any non-obvious abbreviation the first time it appears rather than assuming it's universally understood.
Error Messages Are Documentation Too, Under Pressure
An error message is documentation read at the worst possible moment, when a user or developer is already frustrated and trying to fix something broken. Dense, jargon-heavy error text is especially costly here because the reader has the least patience to parse it. Applying the same sentence-shortening and deliberate-jargon-handling discipline to error copy specifically, not just to long-form docs, pays off disproportionately given how high-stakes that specific reading moment tends to be.
Versioning Reading Level Across a Growing Doc Set
As a documentation set grows across multiple authors and multiple years, reading level tends to drift the same way brand voice does, gradually and unevenly, unless someone is actively checking. A quarterly pass that scores a sample of existing docs, not just new ones, catches pages that were fine when written for an early, more technical audience but have since become a barrier as the product's user base broadened to include less specialized readers.
Localization Makes This Even More Important
Documentation that eventually gets translated compounds every reading-level problem that existed in the source language. Dense, clause-heavy English sentences are harder to translate accurately, and translators working under time pressure sometimes preserve the awkward structure rather than restructuring for the target language's own natural rhythm. Simplifying sentence structure in the source document before translation begins saves real rework across every language the docs eventually ship in, not just the original.
Making It a Standard Pre-Publish Step
Add a readability check to whatever pre-publish checklist your docs already go through, alongside spell check and link verification. It's a two-minute step that catches a failure mode, writing above your actual audience's comfortable reading level, that's otherwise invisible until support tickets start asking questions your doc technically already answered.
The analyzer is free to use and sits alongside the rest of EvvyTools' writing tools if a readability check becomes a regular part of your doc process.
Top comments (0)