Readability scores

To be effective, tech docs need to be accurate, clear, and readable.

Reviewers and subject matter experts (SMEs) help keep things accurate; they also let you know when things aren’t clear.

Studies have shown you can improve readability by lowering the education level needed to understand a piece of writing.

There are many ways to estimate education level, including Flesch-Kindcaid, Gunning fog, and many others.

This article shows how modern writing principles can lower readability scores, which in turn leads to more effective content.

Initial setup

To begin, consider the following text:

Are you passionate about translating complex technical concepts into clear, concise, and engaging content for developers? We’re looking for a skilled Technical Writer to join our team and help us build world-class documentation for our APIs, SDKs, and other developer tools. You’ll play a critical role in shaping how developers interact with our platform—creating guides, reference docs, and tutorials that empower them to build seamlessly and confidently with our technology.

In this role, you’ll collaborate closely with engineers, product managers, and developer advocates to craft content that’s not only technically accurate but also easy to understand and enjoyable to read. Whether you’re documenting a new REST API, writing a walkthrough for a JavaScript SDK, or helping structure a developer portal, your work will have a direct impact on the success of our growing developer community. If you love working at the intersection of code and communication, we want to hear from you.

This sample was originally generated using ChatGPT while working to create a job description for a developer doc role. The goal was to create an introduction that would draw attention and encourage applicants.

Hemingway app reported the sample at a 16th grade reading level, which equates to a senior college student in the US.

As written, the sample has 154 words in six sentences and two paragraphs. Five sentences are classified as very hard to read. There are four adverbs, considered weakeners.

Most readers can read the sample in 37 seconds.

First rewrite

One of the easiest ways to improve readability is to reduce the use of compound or complex sentences. It helps to remove adverbs and other weakeners.

The first rewrite also tries to make the sample more engaging:

Are you passionate about clarity? Do you enjoy translating complicated concepts to concise and engaging content? Are you interested in great code and good security practices?

We’re looking for an experienced Technical Writer to join our team. You’ll create world-class documentation for our APIs, SDKs, and other developer tools. Help developers use our technology to solve their security challenges.

You’ll create guides, reference docs and tutorials. Collaborate with engineers, product managers, and developer advocates. Help developers understand REST APIs, SDKs, integration kits, and examples. Help our developer community solve real-world problems.

If you love working at the intersection of code and communication, we want to hear from you.

Hemingway app grades this at a 10th grade reading level, which is a dramatic improvement over the original (early high school as opposed to near college graduate).

The revised sample has 108 words in eleven sentences and five paragraphs. No sentences are hard to read and there are no weakeners.

Most readers can read the sample in 34 seconds.

Here, you see that a relatively basic edit greatly improves readability.

We can do better, though.

Second rewrite

Consider this version:

We’re looking for an experienced Technical Writer. Help developers use our technology to solve their real-world security challenges.

Are you passionate about clarity? Do you enjoy translating complicated concepts to concise and engaging content? Are you interested in great code and good security practices?

If you love working at the intersection of code and communication, we want to hear from you.

Hemingway app grades this at a 9th grade reading level, which is the level targeted by many tech writing teams.

This version has 61 words in six sentences and three paragraphs. No sentences are hard to read and there are no weakeners.

Most readers can read this in 15 seconds.

This edit is more of a developmental edit than the earlier edit. Content was restructured and focused to improve the narrative flow.

I feel this version flows better and is more engaging.

Improving readability

To improve readability:

1. Use short sentences and lots of whitespace.
2. Use active voice.
3. Be brief and clear.
4. Remove repetition.
5. Use terms familiar to readers.

These should sound familiar.

Calculating scores

Several tools provide interactive readability scores. Examples include Hemingway app, Microsoft Word, and others.

• The Readability Wikipedia article helps you calculate readability using several different techniques and algorithms.

• You can also use the GNU style utility from the diction package to calculate readability scores for text files from a command line.

  For best results, convert Markdown (and other markup formats) to text before running the utility.

  The process varies according to your system.

  On a Mac terminal (or other bash/tsh console), the process might look like:

  % curl -o myfile.html https://example.com/article-URL
  % pandoc -i myfile.html -o myfile.txt --to=plain
  % style myfile.txt
  

  Here, an HTML file is retrieved from a URL and converted to text using the pandoc utility.

  Use your package manager to install the required utilities:

  % brew install pandoc diction
  

  After installing, use % man style to learn more.

• If you use Vale to check your content style, you can create a custom configuration to calculate readability scores. For details, see Alternate rulesets.

Vital statistics

• 16 August 2025: Added Vale customization note.
• 7 June 2025: First post for this website, adapted from a private brown-bag presentation