How Does the B1 English for Developers Certification Work?

This Intermediate level English for Developers Curriculum will help you strengthen the foundational skills developed in the A2 English for developers certification while introducing more complex grammar and expanding on work-related topics.

This entire curriculum will follow the B1 level of the Common European Framework of Reference (CEFR). And, as always, we've focused on vocabulary that is particularly useful for developers.

You'll learn how to describe places and things, share past experiences, and confidently use tenses like Present Perfect and Future. Practical communication strategies are included as well, such as managing conversations, expressing opinions, and building agreement or disagreement in discussions.

You'll also practice vocabulary and phrases essential for developers, such as describing code, participating in meetings, and discussing tech trends. Advanced topics include conditionals, comparative structures, and conversation management, so you can prepare for more complex interactions.

This entire B1-level curriculum includes 73 different dialogues recorded by native English speakers. Each section follows a unique theme, contains several dialogues, and is filled with hundreds of interactive tasks that will help you develop your English skills.

These tasks will introduce new vocabulary, teach grammar, or review concepts that you’ll need to know in order to understand what the characters from the dialogues are saying. Each task will have an accompanying question that will help you practice the content.

The curriculum also has fill-in-the-blank questions that will help you practice writing in English.

Once you’ve completed the certification, you’ll be able to take the B1 English for Developers exam. This exam contains 54 grammar questions, 24 listening questions, and 9 reading questions. All the questions are based on what’s covered in the certification course.

You can take the exam by using our new open source exam environment. The freeCodeCamp community designed this exam environment tool with two goals in mind: respecting your privacy while also making it harder for people to cheat.

Once you download the app to your laptop or desktop, you can take the exam.

Frequently Asked Questions

Is all of this really free?

Yes. freeCodeCamp has always been free, and we’ve now offered free verified certifications for more than a decade. These exams are just the latest expansion to our community’s free learning resources.

Can I study the certification courses in languages other than English?

We aim to make every course available in all supported languages on freeCodeCamp. Check your account settings to see if the course you are studying is already offered in your preferred language.

What language skills does the curriculum cover?

The languages courses currently cover listening, reading, and writing. We have plans to add speaking later on.

Are the audio in the language courses and exams recorded by native language speakers?

Yes. All the audios present in the language courses were recorded by native speakers of that language.

I am Deaf or hard of hearing. Can I still study the language courses?

Yes! All audio lesson have closed captions and transcripts available for reading.

I am blind or have limited vision, and use a screen reader. Can I still study the language courses?

Yes! freeCodeCamp courses are designed to be accessible, and you can study the language courses using a screen reader. If you run into any accessibility issues, you can report them on our GitHub repository so the community can address them.

What are the letters and numbers beside the certification name? (For example: A1, A2, B1)

These labels refer to the CEFR levels, which is an international framework used to describe language proficiency. A1 and A2 represent beginner levels, B1 and B2 represent intermediate levels, and C1 and C2 represent advanced levels.

Each level indicates the skills and knowledge you are expected to have at that stage of your language learning journey.

What prevents people from just cheating on the exams?

Our goal is to strike a balance between preventing cheating and respecting people's right to privacy.

We've implemented a number of reliable, yet non-invasive, measures to help prevent people from cheating on freeCodeCamp's exams:

1. For each exam, we have a massive bank of questions and potential answers to those questions. Each time a person attempts an exam, they'll see only a small, randomized sampling of these questions.

2. We only allow people to attempt an exam one time per week. This reduces their ability to "brute force" the exam.

3. We have security in place to validate exam submissions and prevent man-in-the-middle attacks or manipulation of the exam environment.

4. We manually review each passing exam for evidence of cheating. Our exam environment produces tons of metrics for us to draw from.

We take cheating, and any form of academic dishonesty, seriously. We will act decisively.

This said, no one's exam results will be thrown out without human review, and no one's account will be banned without warning based on a single suspicious exam result.

Are these exams “open book” or “closed book”?

All of freeCodeCamp’s exams are “closed book”, meaning you must rely only on your mind and not outside resources.

Of course, in the real world you’ll be able to look things up. And in the real world, we encourage you to do so.

But that is not what these exams are evaluating. These exams are instead designed to test your memory of details and your comprehension of concepts.

So when taking these exams, do not use outside assistance in the form of books, notes, AI tools, or other people. Use of any of these will be considered academic dishonesty.

Do you record my webcam, microphone, or require me to upload a photo of my personal ID?

No. We considered adding these as additional test-taking security measures. But we have less privacy-invading methods of detecting most forms of academic dishonesty.

If the environment is open source, doesn't that make it less secure?

"Given enough eyeballs, all bugs are shallow." – Linus’s Law, formulated by Eric S. Raymond in his book The Cathedral and the Bazaar

Open source software projects are often more secure than their closed source equivalents. This is because a lot more people are scrutinizing the code. And a lot more people can potentially help identify bugs and other deficiencies, then fix them.

We feel confident that open source is the way to go for this exam environment system.

How can I contribute to the Exam Environment codebase?

It's fully open source, and we'd welcome your code contributions. Please read our general contributor onboarding documentation.

Then check out the GitHub repo.

You can help by creating issues to report bugs or request features.

You can also browse open help wanted issues and attempt to open pull requests addressing them.

Are the exam questions themselves open source?

For obvious exam security reasons, the exam question banks themselves are not publicly accessible. :)

These are built and maintained by freeCodeCamp's staff instructional designers.

What happens if I have internet connectivity issues mid-exam?

If you have internet connectivity issues mid exam, the next time you try to submit an answer, you’ll be told there are connectivity issues. The system will keep prompting you to retry submitting until the connection succeeds.

What if my computer crashes mid-exam?

If your computer crashes mid exam, you’ll be able to re-open the Exam Environment. Then, if you still have time left for your exam attempt, you’ll be able to continue from where you left off.

Can I take exams in languages other than English?

Not yet. We’re working to add multi-lingual support in the future.

I have completed my exam. Why can't I see my results yet?

All exam attempts are reviewed by freeCodeCamp staff before we release the results. We do this to ensure the integrity of the exam process and to prevent cheating. Once your attempt has been reviewed, you'll be notified of your results the next time you log in to freeCodeCamp.org.

I use a keyboard instead of a mouse. Can I navigate the exams using just a keyboard?

This is a high priority for us. We hope to add keyboard navigation to the Exam Environment app soon.

Are exams timed?

Yes, exams are timed. We err on the side of giving plenty of time to take the exam, to account for people who are non-native English speakers, or who have ADHD and other learning differences that can make timed exams more challenging.

If you have a condition that usually qualifies you for extra time on standardized exams, please email support@freecodecamp.org. We’ll review your request and see whether we can find a reasonable solution.

What happens if I fail the exam? Can I retake it?

Yes. You get one exam attempt per week. Afterward, if you don’t pass, there is a one-week (exactly 168 hour) “cool-down” period where you cannot take any freeCodeCamp exams. This is to encourage you to study and to pace yourself.

There is no limit to the number of times you can take an exam. So if you fail, study more, practice your skills more, then try again the following week.

Will the exam be available to take on my phone?

At this time, no. You’ll need to use a laptop or desktop to download the exam environment and take the exam. We hope to eventually offer these certification exams on iPhone and Android.

I have a disability or health condition that is not covered here. How can I request accommodations?

If you need specific accommodations for the exam (for example extra time, breaks, or alternative formats), please email support@freecodecamp.org. We’ll review your request and see whether we can find a reasonable solution.

Anything else?

Good luck working through freeCodeCamp’s languages coursework and preparing for the exam.

Happy learning!

How Does the A2 English for Developers Certification Work?

In this English for Developers Certification, you'll learn the essentials of English communication. This will follow the A2 level of the Common European Framework of Reference (CEFR). And we've focused on vocabulary that is particularly useful for developers.

The first half of the curriculum will help you get comfortable with English grammar and usage. It will give you tons of hands-on practice. You'll learn basics like introducing yourself, making small talk, and discussing your work.

In the second half, you'll practice vocabulary specific to software development. You'll learn how to describe code, discuss tech trends, and participate in meetings.

Each section in this curriculum follows a unique theme, contains several dialogues, and is filled with hundreds of interactive tasks that will help you develop your English skills.

These tasks will introduce new vocabulary, teach grammar, or review concepts that you’ll need to know in order to understand what the characters from the dialogues are saying.

Each task will have an accompanying question that will help you practice the content.

The curriculum also has fill-in-the-blank questions that will help you practice writing in English.

This entire A2-level curriculum includes 105 different dialogues recorded by native English speakers. Each dialogue is designed to build your vocabulary and boost your confidence when speaking in a professional tech setting.

Once you’ve completed the certification, you’ll be able to take the A2 English for Developers exam. This exam contains 48 grammar questions, 36 listening questions, and 24 reading questions. All the questions are based on what’s covered in the certification course.

You can take the exam by using our new open source exam environment. The freeCodeCamp community designed this exam environment tool with two goals: respecting your privacy while also making it harder for people to cheat.

Once you download the app to your laptop or desktop, you can take the exam.

Frequently Asked Questions

Is all of this really free?

Yes. freeCodeCamp has always been free, and we’ve now offered free verified certifications for more than a decade. These exams are just the latest expansion to our community’s free learning resources.

Can I study the certification courses in languages other than English?

We aim to make every course available in all supported languages on freeCodeCamp. Check your account settings to see if the course you are studying is already offered in your preferred language.

What language skills does the curriculum cover?

The languages courses currently cover listening, reading, and writing. We have plans to add speaking later on.

Are the audio in the language courses and exams recorded by native language speakers?

Yes. All the audios present in the language courses were recorded by native speakers of that language.

I am Deaf or hard of hearing. Can I still study the language courses?

Yes! All audio lesson have closed captions and transcripts available for reading.

I am blind or have limited vision, and use a screen reader. Can I still study the language courses?

Yes! freeCodeCamp courses are designed to be accessible, and you can study the language courses using a screen reader. If you run into any accessibility issues, you can report them on our GitHub repository so the community can address them.

What are the letters and numbers beside the certification name? (For example: A1, A2, B1)

These labels refer to the CEFR levels, which is an international framework used to describe language proficiency. A1 and A2 represent beginner levels, B1 and B2 represent intermediate levels, and C1 and C2 represent advanced levels.

Each level indicates the skills and knowledge you are expected to have at that stage of your language learning journey.

What prevents people from just cheating on the exams?

Our goal is to strike a balance between preventing cheating and respecting people's right to privacy.

We've implemented a number of reliable, yet non-invasive, measures to help prevent people from cheating on freeCodeCamp's exams:

1. For each exam, we have a massive bank of questions and potential answers to those questions. Each time a person attempts an exam, they'll see only a small, randomized sampling of these questions.

2. We only allow people to attempt an exam one time per week. This reduces their ability to "brute force" the exam.

3. We have security in place to validate exam submissions and prevent man-in-the-middle attacks or manipulation of the exam environment.

4. We manually review each passing exam for evidence of cheating. Our exam environment produces tons of metrics for us to draw from.

We take cheating, and any form of academic dishonesty, seriously. We will act decisively.

This said, no one's exam results will be thrown out without human review, and no one's account will be banned without warning based on a single suspicious exam result.

Are these exams “open book” or “closed book”?

All of freeCodeCamp’s exams are “closed book”, meaning you must rely only on your mind and not outside resources.

Of course, in the real world you’ll be able to look things up. And in the real world, we encourage you to do so.

But that is not what these exams are evaluating. These exams are instead designed to test your memory of details and your comprehension of concepts.

So when taking these exams, do not use outside assistance in the form of books, notes, AI tools, or other people. Use of any of these will be considered academic dishonesty.

Do you record my webcam, microphone, or require me to upload a photo of my personal ID?

No. We considered adding these as additional test-taking security measures. But we have less privacy-invading methods of detecting most forms of academic dishonesty.

If the environment is open source, doesn't that make it less secure?

"Given enough eyeballs, all bugs are shallow." – Linus’s Law, formulated by Eric S. Raymond in his book The Cathedral and the Bazaar

Open source software projects are often more secure than their closed source equivalents. This is because a lot more people are scrutinizing the code. And a lot more people can potentially help identify bugs and other deficiencies, then fix them.

We feel confident that open source is the way to go for this exam environment system.

How can I contribute to the Exam Environment codebase?

It's fully open source, and we'd welcome your code contributions. Please read our general contributor onboarding documentation.

Then check out the GitHub repo.

You can help by creating issues to report bugs or request features.

You can also browse open help wanted issues and attempt to open pull requests addressing them.

Are the exam questions themselves open source?

For obvious exam security reasons, the exam question banks themselves are not publicly accessible. :)

These are built and maintained by freeCodeCamp's staff instructional designers.

What happens if I have internet connectivity issues mid-exam?

If you have internet connectivity issues mid exam, the next time you try to submit an answer, you’ll be told there are connectivity issues. The system will keep prompting you to retry submitting until the connection succeeds.

What if my computer crashes mid-exam?

If your computer crashes mid exam, you’ll be able to re-open the Exam Environment. Then, if you still have time left for your exam attempt, you’ll be able to continue from where you left off.

Can I take exams in languages other than English?

Not yet. We’re working to add multi-lingual support in the future.

I have completed my exam. Why can't I see my results yet?

All exam attempts are reviewed by freeCodeCamp staff before we release the results. We do this to ensure the integrity of the exam process and to prevent cheating. Once your attempt has been reviewed, you'll be notified of your results the next time you log in to freeCodeCamp.org.

I use a keyboard instead of a mouse. Can I navigate the exams using just a keyboard?

This is a high priority for us. We hope to add keyboard navigation to the Exam Environment app soon.

Are exams timed?

Yes, exams are timed. We err on the side of giving plenty of time to take the exam, to account for people who are non-native English speakers, or who have ADHD and other learning differences that can make timed exams more challenging.

If you have a condition that usually qualifies you for extra time on standardized exams, please email support@freecodecamp.org. We’ll review your request and see whether we can find a reasonable solution.

What happens if I fail the exam? Can I retake it?

Yes. You get one exam attempt per week. Afterward, if you don’t pass, there is a one-week (exactly 168 hour) “cool-down” period where you cannot take any freeCodeCamp exams. This is to encourage you to study and to pace yourself.

There is no limit to the number of times you can take an exam. So if you fail, study more, practice your skills more, then try again the following week.

Will the exam be available to take on my phone?

At this time, no. You’ll need to use a laptop or desktop to download the exam environment and take the exam. We hope to eventually offer these certification exams on iPhone and Android.

I have a disability or health condition that is not covered here. How can I request accommodations?

If you need specific accommodations for the exam (for example extra time, breaks, or alternative formats), please email support@freecodecamp.org. We’ll review your request and see whether we can find a reasonable solution.

Anything else?

Good luck working through freeCodeCamp’s languages coursework and preparing for the exam.

Happy learning!

Why teach English?

For the first 9 years of freeCodeCamp's history, we've mainly focused on teaching math, computer science and programming. So why start teaching English all the sudden?

The answer: millions of developers need to improve their English so they can realize their full career potential.

Internationally, English has become the language of technology, with so many key technologies coming out of the English-speaking world.

English is also the language of business in many countries. I have lots of friends who use English at the office – even though they live in non-English-speaking countries.

In short: it is worth it for most people to invest the time in getting really good at speaking English. And freeCodeCamp is going to help people do this. For free.

A screenshot of freeCodeCamp's English for Developers curriculum, showcasing a listening comprehension challenge and our enhanced accessibility modes.

How freeCodeCamp is teaching English for Developers

We are teaching English interactively, right in your browser.

We're teaching the essentials of English communication. We do this by following the A2 level of the Common European Framework of Reference (CEFR). And we've focused on vocabulary that is particularly useful for developers.

A graphic I created to explain the 6 CEFR levels. freeCodeCamp has started with A2 and will eventually develop B1, B2, C1, and C2.

The first half of the curriculum will help you get comfortable with English grammar and usage. It will give you tons of hands-on practice. You'll learn basics like introducing yourself, making small talk, and discussing your work.

In the second half, you'll practice vocabulary specific to software development. You'll learn how to describe code, discuss tech trends, and participate in stand-up meetings.

This entire A2-level curriculum includes 105 different dialogues. Each is designed to build your vocabulary and boost your confidence when speaking in a professional tech setting.

We've already published 278 English challenges, with videos. And over the coming months we'll publish the rest of Level A2 – more than 1,200 additional challenges.

From there, we'll develop Levels B1, B2, C1, and eventually C2. (We're skipping level A1 since it is covered by most high school and college English courses in most non-English speaking countries.)

I want to give a special thanks to prolific freeCodeCamp contributor Bruce B, who helped us ensure that the curriculum has subtitles and accessibility functions for people with hearing impairment.

This is only the beginning

We'll be working throughout 2024 and 2025 to help as many developers as possible improve their English fluency.

You can get involved in our open source efforts by becoming a volunteer in the freeCodeCamp community.

And if you want to help us speed up development of our English for Developers curriculum, and the many other initiatives we have underway, you should become a monthly supporter of our charity.

Happy English learning. 🏕️

I’m learning how to code.

I'll get a software developer job.

Learning how to code doesn’t have to cost you money.

The words I’m, I’ll and doesn’t are called contractions.

In this article, you'll learn all about contractions – what they are, when and where you'll most likely come across them, when and when not to use them. Finally you'll see some of the most common contractions used in the English language.

Let's get started!

What are contractions?

Contractions, also known as 'short forms', are shortened words.

Specifically, a contraction is when two words are shortened in form and are put together to form one new word.

For example, you and are can be combined to create a shorter word, you’re.

When two words are combined, certain letters will disappear. You can lose just one letter or more, depending on the contraction.

When you combine those two words and the letter(s) disappear, an apostrophe (’) will take their place.

The missing, original letters get replaced by the apostrophe to show the place where the missing letters should be. Those letters will not appear in the contraction (as they've been replaced by the apostrophe).

For example, take the word isn't. This contraction combines the words is and not. When those two get paired together, the letter o disappears. An apostrophe now takes its place to show where the missing letter was.

Another example is when you and will get combined to form you'll. Now two letters disappear,w and i, and the apostrophe fills that space of two missing letters.

When do you use contractions?

We use contractions every day in both speech and writing.

You'll hear them from your friends, family, and on TV. You'll see them in novels, non-fiction books, newspapers, instruction manuals, blog posts, learning material, and much more. There are a couple in this very paragraph, and I use them throughout this article.

They are informal and casual, since they give your writing a more friendly, light, accessible, and approachable tone.

Contractions can make the reader feel like you are talking directly to them and having a conversation. It helps make your writing appear uncomplicated for everyone to understand and make sense of.

Because contractions are shorter, it also means that they take up less space. Because of that, you'll often see them in advertisements where space is valuable.

In a nutshell, you can comfortably use contractions in more informal writing and on relaxed occasions.

When to avoid using contractions

It's best to avoid using contractions when you want to maintain a more serious and formal tone in your writing.

For example, skip using them in academic research papers, important business presentations, or in any situation where informal writing or speech would not make much sense.

Common contractions

Below are some of the most widely used and common contractions you'll encounter when speaking and writing in English.

Common Contractions ending in -ll

Contractions ending in -ll include the word will. The w and i letters get dropped.

Common Contractions ending in -re

Contractions ending in -re include the word are. The letter a gets dropped.

Common Contractions ending in -s

Contractions ending in -s include either the word is or has.

For example:

• He is going = He’s going
• It has gone = It’s gone.

The letter i or the letters h and a, respectively, get dropped.

What about let's ? That is a bit different. let's comes from let + us.

Common Contractions ending in -ve

Contractions ending in -ve include the word have. The letters h and a get dropped.

Common Contractions ending in -d

Contractions ending in -d include either the word had or would.

Some examples with the word had:

• I'd better go now = I had better go now
• I wish I'd never left = I wish I had never left.

Some examples with the word would:

• I'd rather not go there = I would rather not go there
• I'd like something to drink please = I would like something to drink please.

Common Contractions ending in -m

Contractions ending in -m,include the word am.

The letter a gets dropped.

Negative contractions

Negative contractions are those that end in -nt.

You achieve this by adding the word not to a verb, making it negative.

In this case,the letter o gets dropped.

A word that is a little different and an exception to what has been shown so far is won’t – it comes from will + not = won’t.

will does not turn into willn’t. In fact the word "will" does not appear in the contraction at all. Just think of it as an irregular contraction (like how we have irregular verbs).

Common mistakes with contractions

A couple of contractions commonly cause confusion and people often use them in the wrong way - you'll even see native English speakers make these mistakes.

These contractions sound exactly the same with other words, so these mistakes commonly occur in writing.

You’re and Your

You’re is a contraction, a combination of the words you and are.

For example, You’re learning how to code or You’re doing great!.

Your is a possesive pronoun, it is used to indicate that something is owned by/belongs to someone.

For example, Your cat is so cuddly! or Your cooking always tastes so good.

Your doing great makes no sense since it doesn't indicate that something belongs to someone. You’re doing great does, since it indicates action and verbs are used for that.

If you get confused and don't know which to use, read it out to yourself as you are and see if it sounds right.

Your are cat is so cuddly! doesn't make sense or sound right, for example.

It’s and Its

It’s is a contraction – a combinations of it and is or has.

For example, It’s raining outside or It’s been great for me so far, I’m really enjoying it here.

Its is a possesive pronoun. Its shows possession.

For example, Don’t judge a book by its cover or The cat is in its sleeping basket.

Similarly to the example from the previous section, if you're confused use the verbs is or has in your sentence and check to see if it makes sense to add the apostrophe/make it a contraction: Don’t judge a book by it is cover doesn't make sense, so you use the possessive "its" with no apostrophe.

It is raining outside makes sense, so you now know that you can use an apostrophe.

They’re, Their, and There

All three of these words sound the same.

They’re is a contraction. They and are were combined.

For example,They’re going away for the holiday season or They’re buying a house together.

Does the sentence sound right when you use they are? Then use they’re.

Their shows possesion.

For example,Their dog bit me last night or I don’t like their attitude.

Finally, There indicates a place, a location.

For example,I wish I was there instead or I’m never going there again.

Conclusion

And there you have it!

This article gave an overview of contractions and how to use them in both spoken and written English.

You saw some of the most common ones used and some frequent mistakes made when using them.

Thanks for reading!

Datum means "a given" or "something that should be taken into consideration."

Nobody really uses the word "datum." Instead people say "data point" to represent a single unit of data.

So yes – when developers and data scientists say: "the data suggest these two phenomena are correlated" instead of "suggests" – they are indeed using the correct subject-verb agreement for the word "data".

This is not a matter of being cheeky. There is a single objective reality we all live in. And in that reality, the word "data" is plural.

But it's OK for people to say "the data is" instead of "the data are"

It really is.

Life is too short for this kind of nitpicking.

I often hear people who work with data use the wrong subject-verb agreement for the word data. I don't correct them. Because I don't want them to dismiss me as pedantic. Or to take this as some form of deeply-felt criticism.

And I recommend you don't correct people on this, either. It's just not that big a deal.

But remember, there 3 things that can instantly make anyone sound smarter:

• Black frame glasses
• A white lab coat
• Saying "data are" instead of "data is"

Happy coding.

I help the Open Web Application Security Project (OWASP) with their Web Security Testing Guide (WSTG). I was recently tasked with writing a style guide and article template that show how to write technical instruction for testing software applications.

I thought parts of the guide would benefit more people than just OWASP’s contributors, so I’m sharing some here.

Many of the projects I participate in are open source. This is a wonderful way for people to share solutions and to build on each others’ ideas. Unfortunately, it’s also a great way for misused and non-existent words to catch on. Here’s an excerpt of the guide with some mistakes I’ve noticed and how you can fix them in your technical documents.

Use Correct Words

The following are frequently misused words with tips for how to correct them.

and/or

While sometimes used in legal documents, and/or leads to ambiguity and confusion in technical writing. Instead, use or, which in the English language includes and. For example:

Bad: “The code will output an error number and/or description.”
Good: “The code will output an error number or description.”

The latter sentence does not exclude the possibility of having both an error number and description.

If you need to specify all possible outcomes, use a list:

“The code will output an error number, or a description, or both.”

frontend, backend

While it’s true that the English language evolves over time, these are not yet words.

When referring to nouns, use front end and back end. For example:

Security is equally important on the front end as it is on the back end.

As a descriptive adverb, use the hyphenated front-end and back-end.

Both front-end developers and back-end developers are responsible for application security.

whitebox, blackbox, greybox

These are not words.

As nouns, use white box, black box, and grey box. These nouns rarely appear in connection with cybersecurity.

My cat enjoys jumping into that grey box.

As adverbs, use the hyphenated white-box, black-box, and grey-box. Do not use capitalization unless the words are in a title.

While white-box testing involves knowledge of source code, black-box testing does not. A grey-box test is somewhere in-between.

ie, eg

These are letters.

The abbreviation i.e. refers to the Latin id est, which means "that is" or “in other words.” The abbreviation e.g. is for exempli gratia, translating to “for example.” To use these in a sentence:

Write using proper English, i.e. correct spelling and grammar. Use common words over uncommon ones, e.g. “learn” instead of “glean.”

etc

These are also letters.

The Latin phrase et cetera translates to “and the rest.” It is abbreviated etc. and typically placed at the end of a list that seems redundant to complete:

WSTG authors like rainbow colors, such as red, yellow, green, etc.

In technical writing, the use of etc. is problematic. It assumes the reader knows what you’re talking about, and they may not. Violet is one of the colors of the rainbow, but the example above does not explicitly tell you if violet is a color that WSTG authors like.

It is better to be explicit and thorough than to make assumptions of the reader. Only use etc. to avoid completing a list that was given in full earlier in the document.

… (ellipsis)

The ellipsis punctuation mark can indicate that words have been left out of a quote:

Linus Torvalds once said, "Once you realize that documentation should be laughed at… THEN, and only then, have you reached the level where you can safely read it and try to use it to actually implement a driver."

As long as the omission does not change the meaning of the quote, this is acceptable usage of ellipsis in technical writing.

All other uses of ellipsis, such as to indicate an unfinished thought, are not.

ex

While this is a word, it is likely not the word you are looking for. The word ex has particular meaning in the fields of finance and commerce, and may refer to a person if you are discussing your past relationships. None of these topics should appear in technical writing.

The abbreviation ex. may be used to mean “example” by lazy writers. Please don’t be lazy, and write example instead.

Go forth and write docs

If these reminders are helpful, please share them freely and use them when writing your own READMEs and documentation! If there’s some I’ve missed, I’d love to know.

And if you’re here for the comments…

"Change my mind" meme.

If you’d like to help contribute to the OWASP WSTG, please read the contribution guide.

I’ve been using the Hemingway App to try to improve my posts. At the same time I’ve been trying to find ideas for small projects. I came up with the idea of integrating a Hemingway style editor into a markdown editor. So I needed to find out how Hemingway worked!

A screenshot of the Hemingway Editor

Getting the Logic

I had no idea how the app worked when I first started. It could have sent the text to a server to calculate the complexity of the writing, but I expected it to be calculated client side.

Opening developer tools in Chrome ( Control + Shift + I or F12 on Windows/Linux, Command + Option + I on Mac) and navigating to Sources provided the answers. There, I found the file I was looking for: hemingway3-web.js.

Minified file on the top, Formatted file on the bottom. What a difference it makes!

This code is in a minified form, which is a pain to read and understand. To solve this, I copied the file into VS Code and formatted the document (Control+ Shift + I for VS Code). This changes a 3-line file into a 4859-line file with everything formatted nicely.

Exploring the Code

I started to look through the file for anything that I could make sense of. The start of the file contained immediately invoked function expressions. I had little idea of what was happening.

!function(e) {
  function t(r) {
      if (n[r])
          return n[r].exports;
      var o = n[r] = {
          exports: {},
          id: r,
          loaded: !1
      };
...

This continued for about 200 lines before I decided that I was probably reading the code to make the page run (React?). I started skimming through the rest of the code until I found something I could understand. (I missed quite a lot that I would later find through finding function calls and looking at the function definition).

The first bit of code I understood was all the way at line 3496!

getTokens: function(e) {
  var t = this.getAdverbs(e), 
    n = this.getQualifiers(e),
    r = this.getPassiveVoices(e), 
    o = this.getComplexWords(e);
  return [].concat(t, n, r, o).sort(function(e, t) {
    return e.startIndex - t.startIndex
  })
}

And amazingly, all these functions were defined right below. Now I knew how the app defined adverbs, qualifiers, passive voice, and complex words. Some of them are very simple. The app checks each word against lists of qualifiers, complex words, and passive voice phrases. this.getAdverbs filters words based on whether they end in ‘ly’ and then checks whether it’s in the list of non-adverb words ending in ‘ly’.

The next bit of useful code was the implementation of highlighting words or sentences. In this code there is a line:

e.highlight.hardSentences += h

‘hardSentences’ was something I could understand, something with meaning. I then searched the file for hardSentences and got 13 matches. This lead to a line that calculated the readability stats:

n.stats.readability === i.default.readability.hard && (e.hardSentences += 1),
n.stats.readability === i.default.readability.veryHard && (e.veryHardSentences += 1)

Now I knew that there was a readability parameter in both stats and i.default. Searching the file, I got 40 matches. One of those matches was a getReadabilityStyle function, where they grade your writing.

There are three levels: normal, hard and very hard.

t = e.words;
n = e.readingLevel;
return t < 14
  ? i.default.readability.normal
  : n >= 10 && n < 14
    ? i.default.readability.hard
    : n >= 14 ? i.default.readability.veryHard 
      : i.default.readability.normal;

“Normal” is less than 14 words, “hard” is 10–14 words, and “very hard” is more than 14 words.

Now to find how to calculate the reading level.

I spent a while here trying to find any notion of how to calculate the reading level. I found it 4 lines above the getReadabilityStyle function.

e = letters in paragraph;
t = words in paragraph;
n = sentences in paragraph;

getReadingLevel: function(e, t, n) {
  if (0 === t 
 0 === n) return 0;
  var r = Math.round(4.71 * (e / t) + 0.5 * (t / n) - 21.43);
  return r <= 0 ? 0 : r;
}

That means your score is 4.71 average word length + 0.5 average sentence length -21.43. That’s it. That is how Hemingway grades each of your sentences.

Other Interesting Things I Found

• The highlight commentary (information about your writing on the right hand side) is a big switch statement. Ternary statements are used to change the response based on how well you’ve written.
• The grading goes up to 16 before it’s classed as “Post-Graduate” level.

What I’m going to do with this

I am planning to make a basic website and apply what I’ve learned from deconstructing the Hemingway app. Nothing fancy, more as an exercise for implementing some logic. I’ve built a Markdown previewer before, so I might also try to create a writing application with the highlighting and scoring system.

Creating My Own Hemingway App

Having figured out how the Hemingway app works, I then decided to implement what I had learnt to make a much simplified version.

I wanted to make sure that I was keeping it basic, focusing on the logic more that the styling. I chose to go with a simple text box entry box.

Challenges

1. How to assure performance. Rescanning the whole document on every key press could be very computationally expensive. This could result in UX blocking which is obviously not what we want.

2. How to split up the text into paragraphs, sentences and words for highlighting.

Possible Solutions

• Only rescan the paragraphs that change. Do this by counting the number of paragraphs and comparing that to the document before the change. Use this to find the paragraph that has changed or the new paragraph and only scan that one.

• Have a button to scan the document. This massively reduces the calls of the scanning function.

• Use what I learnt from Hemingway — every paragraph is a

  and any sentences or words that need highlighting are wrapped in an internal with the necessary class.

Building the App

Recently I’ve read a lot of articles about building a Minimum Viable Product (MVP) so I decided that I would run this little project the same. This meant keeping everything simple. I decided to go with an input box, a button to scan and an output area.

This was all very easy to set up in my index.html file.

<link rel=”stylesheet” href=”index.css”>
<title>Fake Hemingway</title>
<div>
    <h1>Fake Hemingway</h1>
    <textarea name=”” id=”text-area” rows=”10"></textarea>
    <button onclick=”format()”>Test Me</button>
    <div id=”output”>
    </div>
</div>
<script src=”index.js”></script>

Now to start on the interesting part. Now to get the Javascript working.

The first thing to do was to render the text from the text box into the output area. This involves finding the input text and setting the output’s inner html to that text.

function format() {
    let inputArea = document.getElementById(“text-area”);
    let text = inputArea.value;
    let outputArea = document.getElementById(“output”);
    outputArea.innerHTML = text;
}

Next is getting the text split into paragraphs. This is accomplished by splitting the text by ‘\n’ and putting each of these into a

tag. To do this we can map over the array of paragraphs, putting them in between

tags. Using template strings makes doing this very easy.

let paragraphs = text.split(“\n”);
let inParagraphs = paragraphs.map(paragraph => `<p>${paragraph}</p>`);
outputArea.innerHTML = inParagraphs.join(“ “);

Whilst I was working though that, I was becoming annoyed having to copy and paste the test text into the text box. To solve this, I implemented an Immediately Invoked Function Expression (IIFE) to populate the text box when the web page renders.

(function start() {
    let inputArea = document.getElementById(“text-area”);
    let text = `The app highlights lengthy, …. compose something new.`;
    inputArea.value = text;
})();

Now the text box was pre-populated with the test text whenever you load or refresh the web page. Much simpler.

Highlighting

Now that I was rendering the text well and I was testing on a consistent text, I had to work on the highlighting. The first type of highlighting I decided to tackle was the hard and very hard sentence highlighting.

The first stage of this is to loop over every paragraph and split them into an array of sentences. I did this using a split() function, splitting on every full stop with a space after it.

let sentences = paragraph.split(‘. ’);

From Heminway I knew that I needed to calculate the number of words and level of each of the sentences. The level of the sentence is dependant on the average length of words and the average words per sentence. Here is how I calculated the number of words and the total words per sentence.

let words = sentence.split(“ “).length;
let letters = sentence.split(“ “).join(“”).length;

Using these numbers, I could use the equation that I found in the Hemingway app.

let level = Math.round(4.71 * (letters / words) + 0.5 * words / sentences — 21.43);

With the level and number of words for each of the sentences, set their difficulty level.

if (words < 14) {
    return sentence;
} else if (level >= 10 && level < 14) {
    return `<span class=”hardSentence”>${sentence}</span>`;
} else if (level >= 14) {
    return `<span class=”veryHardSentence”>${sentence}</span>`;
} else {
    return sentence;
}

This code says that if a sentence is longer than 14 words and has a level of 10 to 14 then its hard, if its longer than 14 words and has a level of 14 or up then its very hard. I used template strings again but include a class in the span tags. This is how I’m going to define the highlighting.

The CSS file is really simple; it just has each of the classes (adverb, passive, hardSentence) and sets their background colour. I took the exact colours from the Hemingway app.

Once the sentences have been returned, I join them all together to make each of the paragraphs.

At this point, I realised that there were a few problems in my code.

• There were no full stops. When I split the paragraphs into sentences, I had removed all of the full stops.
• The numbers of letters in the sentence included the commas, dashes, colons and semi-colons.

My first solution was very primitive but it worked. I used split(‘symbol’) and join(‘’) to remove the punctuation and then appended ‘.’ onto the end. Whist it worked, I searched for a better solution. Although I don’t have much experience using regex, I knew that it would be the best solution. After some Googling I found a much more elegant solution.

let cleanSentence = sent.replace(/[^a-z0–9. ]/gi, “”) + “.”;

With this done, I had a partially working product.

Hard sentence highlighting

The next thing I decided to tackle was the adverbs. To find an adverb, Hemingway just finds words that end in ‘ly’ and then checks that it isn’t on a list of non-adverb ‘ly’ words. It would be bad if ‘apply’ or ‘Italy’ were tagged as adverbs.

To find these words, I took the sentences and split them into an arary of words. I mapped over this array and used an IF statement.

if(word.match(/ly$/) &&, !lyWords[word] ){
    return `<span class=”adverb”>${word}</span>`;
} else {
    return word
};

Whist this worked most of the time, I found a few exceptions. If a word was followed by a punctuation mark then it didn’t match ending with ‘ly’. For example, “The crocodile glided elegantly; it’s prey unaware” would have the word ‘elegantly;’ in the array. To solve this I reused the .replace(/^a-z0-9. ]/gi,””) functionality to clean each of the words.

Another exception was if the word was capitalised, which was easily solved by calling toLowerCase()on the string.

Adverbs working

Now I had a result that worked with adverbs and highlighting individual words. I then implemented a very similar method for complex and qualifying words. That was when I realised that I was no longer just looking for individual words, I was looking for phrases. I had to change my approach from checking if each word was in the list to seeing if the sentence contained each of the phrases.

To do this I used the .indexOf() function on the sentences. If there was an index of the word or phrase, I inserted an opening span tag at that index and then the closing span tag after the key length.

let qualifiers = getQualifyingWords();
let wordList = Object.keys(qualifiers);
wordList.forEach(key => {
    let index = sentence.toLowerCase().indexOf(key);
    if (index >= 0) {
    sentence =
        sentence.slice(0, index) +
        ‘<span class=”qualifier”>’ +
        sentence.slice(index, index + key.length) +
        “</span>” +
        sentence.slice(index + key.length);
    }
});

With that working, it’s starting to look more and more like the Hemingway editor.

Getting complex phrases and qualifiers working

The last piece of the highlighting puzzle to implement was the passive voice. Hemingway used a 30 line function to find all of the passive phrases. I chose to use most of the logic that Hemingway implemented, but order the process differently. They looked to find any words that were in a list (is, are, was, were, be, been, being) and then checked whether the next word ended in ‘ed’.

I looped though each of the words in a sentence and checked if they ended in ‘ed’. For every ‘ed’ word I found, I checked whether the previous word was in the list of pre-words. This seemed much simpler, but may be less performant.

With that working I had an app that highlighted everything I wanted. This is my MVP.

All the highlighting working

Then I hit a problem

As I was writing this post I realised that there were two huge bugs in my code.

// from getQualifier and getComplex
let index = sentence.toLowerCase().indexOf(key);
// from getPassive
let index = words.indexOf(match);

These will only ever find the first instance of the key or match. Here is an example of the results this code will produce.

Code with bugs in

‘Perhaps’ and ‘been marked’ should have been highlighted twice each but they aren’t.

To fix the bug in getQualifier and getComplex, I decided to use recursion. I created a findAndSpan function which uses .indexOf() to find the first instance of the word or phrase. It splits the sentence into 3 parts: before the phrase, the phrase, after the phrase. The recursion works by passing the ‘after the phrase’ string back into the function. This will continue until there are no more instances of the phrase, where the string will just be passed back.

function findAndSpan(sentence, string, type) {
    let index = sentence.toLowerCase().indexOf(key);
    if (index >= 0) {
        sentence =
            sentence.slice(0, index) +
            `<span class="${type}">` +
            sentence.slice(index, index + key.length) +
            "</span>" +
            findAndSpan(
                sentence.slice(index + key.length), 
                key,
                type);
    }
    return sentence;
}

Something very similar had to be done for the passive voice. The recursion was in an almost identical pattern, passing the leftover array items instead of the leftover string. The result of the recursion call was spread into an array that was then returned. Now the app can deal with repeated adverbs, qualifiers, complex phrases and passive voice uses.

Statistics Counter

The last thing that I wanted to get working was the nice line of boxes informing you on how many adverbs or complex words you’d used.

To store the data I created an object with keys for each of the parameters I wanted to count. I started by having this variable as a global variable but knew I would have to change that later.

Now I had to populate the values. This was done by incrementing the value every time it was found.

data.sentences += sentence.length
or
data.adverbs += 1

The values needed to be reset every time the scan was run to make sure that values didn’t continuously increase.

With the values I needed, I had to get them rendering on the screen. I altered the structure of the html file so that the input box and output area were in a div on the left, leaving a right div for the counters. These counters are empty divs with an appropriate id and class as well as a ‘counter’ class.

<div id=”adverb” class=”adverb counter”></div>
<div id=”passive” class=”passive counter”></div>
<div id=”complex” class=”complex counter”></div>
<div id=”hardSentence” class=”hardSentence counter”></div>
<div id=”veryHardSentence” class=”veryHardSentence counter”></div>

With these divs, I used document.querySelector to set the inner html for each of the counters using the data that had been collected. With a little bit of styling of the ‘counter’ class, the web app was complete. Try it out here or look at my code here.

The completed app