Free tool

Lesson readability checker

Paste a lesson and see how easy it is to read: the Flesch reading ease score and grade level for the whole text and for every section, with the long sentences, passives and long words behind a low score. Code is ignored.

Free, no sign-up. Nothing you type leaves your browser.

Your lesson

Lesson text (Markdown or plain text, in English)

# Calling an API with fetch

In this lesson you'll ask a web server for data and show it on the page. You'll use `fetch`, which is built into every modern browser. By the end, your page will list books from a real API.

## What an API is

An API is a way for one program to talk to another. You send a request to a web address. The server sends back a response, usually as JSON. You don't need to know how the server works inside. You only need to know what to ask for and what comes back.

## Make your first request

Open the starter project and add this to `app.js`:

```js
const response = await fetch('https://api.example.com/books');
const books = await response.json();
console.log(books);
```

The word `await` tells the browser to wait for the answer before it runs the next line. Save the file and reload the page. Then open the browser console. You should see a list of books.

## Keeping your key safe

Authentication credentials are issued to each developer upon registration and must be included in the authorisation header of every request that is transmitted to a protected endpoint. They should never be committed to a version control repository, since any credential that has been exposed in this manner must be considered compromised and should be revoked immediately by the organisation's administrator. Environment variables are generally regarded as the most appropriate mechanism for configuration of this nature.

## Check that it worked

- The console shows a list, not an error
- Each book has a title and an author
- Your key isn't in any file you committed
- You can say in one sentence what `fetch` gives back

Sections are its ## and ### headings. Headings, tables and code blocks aren’t scored; inline code and links count as one short word.

Flag sentences longer than (words)

25 is a common rule of thumb for plain English, not a hard limit.

Flesch reading ease

68 Plain English

Easily understood by 13- to 15-year-olds. Flesch–Kincaid grade level 6.8 (US school grade).

244words scored

20sentences

12.2words a sentence

By section

Section	Words	Ease	Grade
Introduction	38	92Very easy	3.6
What an API is	52	91Very easy	3.2
Make your first request	45	94Very easy	2.3
Keeping your key safeHardest to read	75	5Very difficult	18.7
Check that it worked	34	94Very easy	2.3

Sections under 30 words get a rough score: one sentence moves it a lot.

Long sentences (over 25 words: 2)

33 words · Keeping your key safeThey should never be committed to a version control repository, since any credential that has been exposed in this manner must be considered compromised and should be revoked immediately by the organisation's administrator.
27 words · Keeping your key safeAuthentication credentials are issued to each developer upon registration and must be included in the authorisation header of every request that is transmitted to a protected endpoint.

Possible passives (9)

is built
are issued
be included
is transmitted
be committed
been exposed
be considered
be revoked
are generally regarded

A form of “to be” before a past participle. It’s a heuristic: check each one, and rewrite the ones that hide who does what.

Words of 4+ syllables (15)

administrator
authentication
authorisation
configuration
immediately
organisation's
repository
appropriate
developer
environment
generally
mechanism
registration
usually
variables

The formulas were made for English and only count sentence length and syllables. Syllables are counted from spelling, so a few words will be off by one.

How to use the checker

Paste your lesson in Markdown or plain text. Its ## and ### headings become the rows of the section table.
Read the overall score and its band, from “very easy” to “very difficult”.
Find the hardest section. It’s marked in the table. A lesson can score well overall and still have one section that loses people.
Look at why. The long sentences, possible passives and long words are listed below the table.
Edit and watch the score. It updates as you type. Copy the report if you want to share it.

What the scores mean

Flesch reading ease comes from Rudolf Flesch (1948). It is 206.835 − 1.015 × (words ÷ sentences) − 84.6 × (syllables ÷ words). Long sentences and long words both pull it down. The Flesch–Kincaid grade level, from J. Peter Kincaid and colleagues (1975), uses the same two counts to estimate a US school grade: 0.39 × (words ÷ sentences) + 11.8 × (syllables ÷ words) − 15.59. Lower is easier.

Reading ease	Band	Usually read easily by
90–100	Very easy	An average 11-year-old
80–89	Easy	Anyone: conversational English
70–79	Fairly easy	Most adults
60–69	Plain English	13- to 15-year-olds
50–59	Fairly difficult	Adults, with some effort
30–49	Difficult	Readers used to academic text
0–29	Very difficult	University graduates

Only prose is scored. Headings, tables and code blocks are left out, and a piece of inline code or a URL counts as one short word, so useEffectCleanup doesn’t count as a five-syllable word. Syllables are counted from spelling with rules for English (vowel groups, a silent final e, -le, -ed and so on), so a few words will be off by one.

Why readability matters more in technical lessons

In a technical lesson, learners already work hard on the content: new ideas, new commands, and terms you can’t avoid, like “endpoint” or “repository”. Working memory is limited, and every long sentence asks them to hold more of it at once. You can’t make the terms shorter, so make everything around them easy: short sentences, common words, one step at a time.

It matters even more when many of your learners read English as a second language, as they often do in international bootcamps and company academies. Plain sentences cost them far less than dense ones.

How to fix a hard section

One idea per sentence. Split where a sentence turns with “which”, “since” or a second “and”.
Put the person first. “Never commit your key” is shorter and clearer than “Keys should never be committed”.
Define terms once, in plain words, then use the same term every time.
Prefer the short word when it means the same: “use” for “utilise”, “about” for “regarding”. Keep the technical terms; learners need them.
Turn steps into a numbered list. Each item becomes its own short sentence.
Read it aloud. Where you run out of breath, the sentence is too long.

A worked example

The example in the checker is an API lesson for a JavaScript bootcamp. Overall it scores 68, plain English, but one section, “Keeping your key safe”, scores 5 out of 100. Its three sentences average 25 words, its words average 2.08 syllables, and the checker finds eight possible passives in it: “are issued”, “be included”, “be committed” and five more. Here is the same section rewritten:

Your API key proves who you are. Send it in the Authorization header of every request. Never commit it to Git: anyone who sees it can use it. If a key ends up in a commit, revoke it straight away and make a new one. Keep the key in an environment variable instead, and add your .env file to .gitignore.

	Before	After
Words a sentence	25	12
Syllables a word	2.08	1.30
Reading ease	5 (very difficult)	85 (easy)
Grade level	18.7	4.4

The rewrite keeps every instruction, and each sentence now tells the learner what to do. To see exactly what changed between two versions like these, paste them into the Markdown diff checker.

What the formulas can’t tell you

They count; they don’t understand. A sentence can score well and still be wrong, vague or in the wrong order.
Short words aren’t always easy. In Git, “head”, “fork” and “tree” are short words with new meanings. Define them anyway.
Short sections swing. Under about 30 words, one sentence moves the score a lot, so the checker marks those scores as rough.
They are for English. Use them on English text only.

Use the score to find the section worth a second look, then read it as a learner would. Length matters too: the reading time calculator shows how long each section takes to read.

Questions people ask

What is a good Flesch reading ease score?

60 or above is plain English, which suits most lesson text. Technical lessons often land between 50 and 60 because the terms themselves are long. Below 50, look at sentence length first: it is usually easier to fix than the vocabulary.

What is the difference between Flesch reading ease and the Flesch–Kincaid grade level?

Both use the same two measures, words per sentence and syllables per word, with different weights. Reading ease runs from about 0 (very difficult) to 100 (very easy). The grade level estimates the US school grade a reader needs, so lower is easier.

How do I make a lesson easier to read?

Give each sentence one idea, put the person doing the action first, and use a short word where it means the same as a long one. Define each technical term the first time you use it, then check the section again.

Does the readability checker work for other languages?

No. Both formulas were made for English, and the syllable counting here follows English spelling. Other languages have their own adapted formulas, so a score for them here would mislead you.

Is passive voice always wrong?

No. It’s fine when it doesn’t matter who acts, as in “the file is created automatically”. It becomes a problem when it hides who has to act, and in a lesson that is usually the learner.

Is my text stored anywhere?

No. The checker runs in your browser; nothing you paste is sent to a server or saved.

More free tools

All free tools →

Reading

Do this for every lesson, every group

Chalkenso is where courses are designed and improved: instructors note what happened on the exact passage, learners say where they got stuck, and AI drafts the next version for you to approve.

Join the waitlist How it works

Join the waitlist